HOWTO and Express Tutorial for Privileged DFC Build 6

Transcription

1 HOWTO and Express Tutorial for Privileged DFC Build 6 Overview End-users with special requirements at times need limited scope permission/privilege (P 2 ) escalation. P 2 escalation means momentarily overriding administrative rights to acquire a specific greater right at runtime under controlled conditions for the focused purpose to carry out a well-defined operation. Privilege escalation begins and terminates within a precise, defined and usually short time window. Privilege escalation is not an openended acquisition of higher privilege. The Big Picture Business Object Framework (BOF) entities may need, for some legitimate reason, to acquire on-the-fly P 2 to which they are not otherwise entitled. For instance, Figure 1 represents an attempt by a BOF entity to execute a task for which it owns partial administrative permission (partial and permission here have an intentionally vague meaning). This task has an internal dependency on a highly privileged subtask needed to complete part of the work. Since the BOF entity does not have sufficient administrative permission to run the highly privileged task, execution will fail. This is, in most cases, the desired outcome. It is possible, however, that a trusted BOF entity is known to need escalation. In this case the desired outcome is for execution to succeed. Privilege escalation is a mechanism for enabling successful execution. It can allow the task to succeed even if there is a highly privileged dependency beyond the scope of the trusted BOF entity administrative permissions. (Failure from insufficient P 2 is here a defect.) In Figure 2 the execution attempt succeeds thanks to a provisional escalation of security that allows the BOF entity to run the highly privileged dependency. Administrative security permissions for the BOF entity are identical: they are the same as in the previous case. Yet, because the BOF entity is trusted and known to need escalation, a security escalation environment enables this BOF entity to acquire on the fly additional temporary privileges sufficient to carry out execution of the highly privileged subtask, and shed these privileges again when not needed anymore. Page 1

2 Figure 1 - Incomplete Escalation Figure 2 - Privilege Escalation Page 2

3 P 2 escalation depends on the existence of all of the following: a trusted BOF entity, a known need for privilege escalation, an escalation mechanism to grant privileges or permissions. A Module Example This is a how-to, so here is the code. First the module interface: package com.documentum.test.bof.priv.simplehowto; import com.documentum.fc.common.dfexception; import com.documentum.fc.client.idfmodule; import com.documentum.fc.client.idfmodulecategory; /** * Example of escalation with Privileged DFC * 6.0 */ public interface ISimpleEscalatingModule extends IDfModule, IDfModuleCategory void settitle ( final String folderpath, final String objectname, final String newtitle, final String inrolename) throws DfException; String modulename = "simpleescalationexamplemodule"; String unprivilegedusername = "<myunprivilegeduser>"; String unprivilegeduserpassword = "<myunprivilegeduserpasswd>"; String docbasename = "<mydocbase"; Next the module implementation: package com.documentum.test.bof.priv.simplehowto; import com.documentum.fc.common.dfexception; import com.documentum.fc.common.idflogininfo; import com.documentum.fc.common.dflogininfo; import com.documentum.fc.client.idfsession; import com.documentum.fc.client.idfsysobject; import com.documentum.fc.client.idfsessionmanager; import com.documentum.fc.client.idfclient; import com.documentum.fc.client.dfclient; Page 3

4 import com.documentum.fc.client.idffolder; import com.documentum.fc.client.security.dfprivilegedexceptionactioninrole; import com.documentum.fc.client.security.dfrolespec; import java.security.accesscontroller; import java.security.privilegedexceptionaction; import java.security.privilegedactionexception; /** * Example of escalation with Privileged DFC * 6.0 */ public class SimpleEscalatingModule implements ISimpleEscalatingModule public String getname () return modulename; public void settitle ( final String folderpath, final String objectname, final String newtitle, final String inrolename) throws DfException final IDfSession session = getsessionwithunprivilegeduser(); try AccessController.doPrivileged( new DfPrivilegedExceptionActionInRole<String>( new DfRoleSpec(inRoleName), true, new PrivilegedExceptionAction<String>() public String run () throws DfException IDfFolder folder= null; if (null!=folderpath && 0<folderPath.length()) folder = session.getfolderbypath(folderpath); String qualification = "dm_document where object_name = '" + objectname + (null==folder?"'": ("' and FOLDER(ID('" + folder.getobjectid() + "'))")); IDfSysObject object = (IDfSysObject) session.getobjectbyqualification(qualification); object.settitle(newtitle+(new java.util.date())); object.save(); return null; Page 4

5 )); catch ( PrivilegedActionException e) Exception realexception = e.getexception(); if ( realexception instanceof DfException ) throw (DfException)realException; else throw new DfException(realException); catch ( RuntimeException e) throw e; finally releasesession(session); private IDfSession getsessionwithunprivilegeduser () throws DfException client = DfClient.getLocalClient(); sm = client.newsessionmanager(); login = new DfLoginInfo( unprivilegedusername, unprivilegeduserpassword); sm.setidentity(docbasename, login); return sm.getsession(docbasename); private void releasesession(idfsession session) sm.release(session); protected IDfSessionManager sm; protected IDfClient client; protected IDfLoginInfo login; The above module is compiler ready, just set a suitable user, password and docbase. Provided everything is configured properly, any unprivilegedusername will be able to set the title of a document and save it, even if that user does not have administrative permission to do so. Besides the additional out-of-band configuration, the only peculiar trait of the above module is this: AccessController.doPrivileged( new DfPrivilegedExceptionActionInRole<String>( new DfRoleSpec(inRoleName), true, new PrivilegedExceptionAction<String>() public String run () throws DfException Page 5

6 // escalated DFC code goes here )); The JVM that runs DFC will inspect all stack activation frames included between the current one (top of the stack, i.e. most recent call) and the last frame activated prior to the invocation of the AccessController.doPrivileged block. (We shall call security context the scope of the inspection.) Java will check if any frame lacks a particular permission associated with the lexical value of the String inrolename. If no lack is found, then execution continues. If any stack frame in the security context lacks this permission then execution terminates with an exception. The purpose of AccessController.doPrivileged is not to effect the check (the check happens in any case when escalation is requested), but to limit from below the depth of the active stack frames subject to checking, so as not to include in the security context other frames outside of the module that would certainly fail to pass such check. Therefore, AccessController.doPrivileged is not an enforcement mechanism, but rather an enablement mechanism: the check is done in any case, but without using AccessController.doPrivileged it will certainly fail as it would include calls made outside of the privileged module in activation frames without the escalation permission. Why would it be so? Since the module acquires the needed permission (as in java.security.permission) associated with the lexical value of the String inrolename at load time, it follows that other code not part of this privileged module did not acquire any permissions at load time. The other code cannot escalate with the privilege of inrolename. Of course, there is additional configuration to carry out. Assuming you can install the.jar files for the above module as usual (e.g. as done in Documentum 5.3), the following driver enables escalation programmatically in DFC 6.0. package com.documentum.test.bof; import com.documentum.fc.client.idfsession; import com.documentum.fc.client.idfgroup; import com.documentum.fc.client.idfdocument; import com.documentum.fc.client.idfacl; import com.documentum.fc.client.dfclient; import com.documentum.fc.client.idfsessionmanager; import com.documentum.fc.client.idfclient; import com.documentum.fc.client.idffolder; import com.documentum.fc.client.idfsysobject; import com.documentum.fc.client.idfpersistentobject; import com.documentum.fc.client.impl.bof.cache.classcachemanager; import com.documentum.fc.common.dfexception; import com.documentum.fc.common.dflogininfo; import com.documentum.fc.common.idflogininfo; import com.documentum.test.bof.priv.simplehowto.isimpleescalatingmodule; Page 6

7 /** * Driver for simple escalation example. * 6.0 */ public class ZSimpleEscalationHowtoDriver public ZSimpleEscalationHowtoDriver() throws DfException client = DfClient.getLocalClient(); sm = client.newsessionmanager(); login = new DfLoginInfo( privilegedusername, privilegeduserpassword); sm.setidentity(docbasename, login); session = sm.getsession(docbasename); private IDfACL createacl( IDfSession session, String rolename) throws DfException IDfACL acl = (IDfACL) session.newobject("dm_acl"); acl.grant("dm_owner", 7, null); acl.grant(rolename, 7, null); acl.save(); return acl; private IDfDocument createobject ( IDfSession session, IDfACL acl, String objectname) throws DfException IDfPersistentObject object = session.getobjectbypath(objectname); if (null!=object) object.destroy(); IDfDocument document = (IDfDocument) session.newobject("dm_document"); document.setobjectname(objectname); document.settitle("testdocumenttitle"); document.setacl(acl); document.save(); return document; private void createprotectedrole ( IDfSession session, String rolename) throws DfException IDfGroup role = session.getgroup(rolename); if (role == null) Page 7

8 role = (IDfGroup) session.newobject("dm_group"); role.setgroupname(rolename); role.setdynamic(true); role.setboolean("is_protected", true); role.addgroup("dm_world"); role.save(); private void makemoduleprivileged ( IDfSession session, String modulename, String rolename) throws DfException IDfFolder module = (IDfFolder) session.getobjectbyqualification( "dmc_module where object_name='" + modulename + "'"); module.setboolean("a_is_privileged", true); module.truncate("a_privilege_roles", 0); module.appendstring("a_privilege_roles", rolename); module.save(); ClassCacheManager.getInstance(). requestcacheconsistencycheck(); private void initialize() throws DfException createprotectedrole(session, rolename); makemoduleprivileged(session,modulename,rolename); IDfACL acl = createacl(session,rolename); createobject(session, acl, objectname); private ISimpleEscalatingModule getmodule ( IDfSessionManager sm) throws DfException return (ISimpleEscalatingModule) DfClient.getInstance().newModule( docbasename, modulename, sm); private IDfSysObject getbyqualitification( IDfSession session, String folderpath, String objectname) throws DfException IDfFolder folder= null; if (null!=folderpath && 0<folderPath.length()) folder = session.getfolderbypath(folderpath); String qualification = Page 8

9 "dm_document where object_name = '" + objectname + (null==folder?"'": ("' and FOLDER(ID('" + folder.getobjectid() + "'))")); IDfSysObject object = (IDfSysObject) session.getobjectbyqualification(qualification); return object; public static void main (String[] args) ZSimpleEscalationHowtoDriver driver = null; try driver = new ZSimpleEscalationHowtoDriver(); driver.initialize(); IDfSysObject object = driver.getbyqualitification( driver.session,"",objectname); System.out.println( "old title: "+object.gettitle()); ISimpleEscalatingModule module = driver.getmodule(driver.sm); module.settitle(null,objectname, "Title set by module on ",driver.rolename); object = driver.getbyqualitification( driver.session,"",objectname); System.out.println("new title: "+object.gettitle()); catch (DfException e) System.out.println("**** Ohps! ****"); e.printstacktrace(); finally driver.sm.release(driver.session); final static String modulename = "simpleescalationexamplemodule"; private final static String objectname = "TheNameOfThisObject_1234XQ"; private final String privilegedusername = "<myprivilegedusername>"; private final String privilegeduserpassword = "<myprivilegeduserpasswd>"; private final String docbasename = "<mydocbase>"; private final String rolename = "my_rw_escalation_role"; private IDfSessionManager sm; private IDfClient client; private IDfLoginInfo login; private final IDfSession session; Page 9

10 That is lengthy, but again, it is also compiler ready after setting a suitable user, password and docbase. Out-of-band configuration for running Privileged DFC include several steps in addition to what BOF requires, for instance, in Documentum 5.3. These steps are: create an escalation role (createprotectedrole) make the module privileged (makemoduleprivileged) create a suitable ACL (createacl), recommended but not strictly necessary under certain circumstances All can be carried out programmatically, and most of them can be carried out administratively in build 6. One last thing is needed before running: in a suitable location (see appendix) it is necessary to create the file.java.policy with this content (or to edit the file, if already existing): grant codebase "<fully qualified dfc.jar filename>" permission com.documentum.fc.client.impl.bof.security.rolepermission "*", "propagate"; ; After this hands-on introduction [ALL WORKS AS SESCRIBED IN BUILD 6] let s tackle a bit of background information. Design and Administration Before Runtime Privileged DFC is appropriate if a module that runs with insufficient administrative permissions must carry out a critical part of its overall operation that needs greater privilege. To start taking advantage of Privileged DFC it is necessary, among the rest, to plan privilege usage and know with certainty what the administrative permissions of the module will be (i.e. what username/password will be used to run it) identify all critical functionality with insufficient administrative permissions define without ambiguity what additional P 2 this critical functionality requires assess what dependencies on external code the critical functionality may have (e.g. what calls to external libraries that are not DFC core 1 it will make) analyze execution and determine potential security issues o in the critical functionality 1 The following namespaces: com.documentum.fc.* com.documentum.dmcl.* com.documentum.djcb.* com.documentum.operations.* com.documentum.registry.* com.documentum.tracing.* com.documentum.vdm.* com.documentum.xml.* define DFC core. All DFC namespaces are sealed in DFC 6.0: BOF code is not allowed in any DFC core namespaces. Page 10

11 o in the external dependencies decide if external dependencies may or must not be privileged find alternate solutions for dependencies that must not be privileged Once privileged usage is determined, it will become clear what additional P 2 the escalation with Privileged DFC must provide to the running code, and if these additional P 2 must be granted to the module alone (a normal escalation) or to the module and its external dependencies as well (a propagating escalation). Privileged DFC uses a dynamic security model based on roles to make available such additional P 2. It is mandatory to design these roles to provide exactly what runtime P 2 the critical code needs: Too little P 2 will be insufficient for successful execution. Too much P 2 offers potential for abuse or disaster and is in general bad practice. Privilege roles need identifiers. Here are the lexical rules for creating identifiers given to custom roles, whose names are arbitrary within the following constraints: must NOT begin with the lowercase characters dm_ only a sequence of characters from the set [a-za-z_] is allowed length must not exceed 32 characters For instance, if we have determined that our hypothetical module Foo needs exactly <update doc object> runtime P 2 to carry out its mission, then we know enough at this point to declare a role for Privileged DFC. Let the name of this role be role_foo_update as an example. Module Foo should acquire at runtime <update doc object> (no more, no less) in addition to the normal administrative permissions associated with it. Here, <update doc object> is a placeholder that conveys a meaning, rather than the details of how to bring that meaning to existence we re not quite there yet. Hypothetically, let module Foo include a java class named Bar with a method named updatemyobject(). This method throws DfException, returns a Boolean and must have <update doc object> P 2 to succeed. The escalation is normal (i.e. it does not need to propagate). To exercise runtime escalation the method, among the rest, must be invoked in a privileged block associated with role_foo_update The above is accomplished as in the following code snippet: [ ] import com.documentum.fc.client.security.dfrolespec; import com.documentum.fc.client.security. DfPrivilegedExceptionActionInRole; [ ] Page 11

12 [ ] final Bar mybar = this; try return AccessController.doPrivileged( new DfPrivilegedExceptionActionInRole<Boolean>( new DfRoleSpec( role_foo_update ), new PrivilegedExceptionAction<Boolean>() public Boolean run () throws DfException return mybar.updatemyobject(); )); catch (PrivilegedActionException e) Exception realexception = e.getexception(); if ( realexception instanceof DfException ) throw (DfException)realException; else throw new DfException(realException); catch ( RuntimeException e) throw e; [ ] Now we know enough to code our module (which we have just done), and we have the information to configure the escalation, which we ll do next. First, using Documentum Application Builder or programmatically through a user with administrative privilege we go through the usual exercise of installing the module. In addition, we must set two new attributes in dmc_module: Attribute name Data type Single / Description Repeating a_is_privileged Boolean Single true if the module is privileged, false otherwise. Set at installation only. a_privilege_roles String repeating if a_is_privileged is true, this is the list of roles the module may assume. Otherwise, it must be empty. Set at installation only. This is the list of possible value of these combined attributes: a_is_privileged false a_privilege_roles empty (must be empty) Page 12

13 a_is_privileged true a_privilege_roles non-empty (must not be empty) For our module Foo, a_is_privileged is true, and a_privilege_roles is exactly equal to the lexical token role_foo_update Next, we need to configure the content server (for instance, using DA) and define role_foo_update. Roles eventually map onto the content server to dynamic groups crafted for the purpose. The following is a list of what runtime P 2 are available for escalation out-of-the-box for all D6 content servers: Superuser Role (dm_superusers_role) Default permissions: Inclusion in dm_superusers group Default membership: None Superuser Role (dm_browse_all_role) Default permissions: Inclusion in dm_browse_all group Default membership: None Sysadmin Role (dm_sysadmin_role) Default permissions: Inclusion in dm_sysadmin group Default membership: None User Identity Override Role (dm_user_identity_override_role) Default permissions: Has Object-Modifier-Control rights Default membership: dm_world Datefield Override Role (dm_datefield_override_role) Default permissions: Has Object-Timestamp-Control rights Default membership: dm_world Internal Attribute Override Role (dm_internal_attribute_override_role) Default permissions: Has Object-Attribute-Override rights Default membership: dm_world Assume User Role (dm_assume_user_role) Default permissions: Inclusion in dm_assume_user group. Default membership: dm_world All these default roles (their identifiers begin with the reserved dm_ prefix) are protected by default, which means that the role is available for exercise if and only if the dfc asking escalation privilege is registered with the server. Also, none of these roles are appropriate for Foo. For our module Foo it is appropriate to create a custom role role_foo_update comprising <update doc object> that (meaning update to include delete) can be realized Page 13

14 with an ACL accessorpermit value of 7. All this can be done programmatically (access must be available with sufficient administrative permissions) for instance like this: (IDfGroup) role = (IDfGroup) session.newobject("dm_group"); role.setgroupname( role_foo_update ); role.setdynamic(true); role.setboolean("is_protected", true); if (istightlycontrolledaccess) role.adduser( <sessionusername> ); else role.addgroup( dm_world ); role.save(); Note that is_protected is set to true. ACL for the target object could be IDfACL acl = (IDfACL)session.newObject("dm_acl"); acl.grant( dm_world, 1, null); acl.grant( dm_owner, 7, null); acl.grant( role_foo_update, 7, null); acl.save(); What if I need superuser power? Well, there are rare occasions where you really can t do without that. If this is the case, instead of defining a custom role you may instead use an appropriate out-of-the-box dm_* role: associate your privileged code with the matching dm_* lexical token. don t forget to update the membership of the role with your user or group, if necessary (e.g. when acting on an object that is not browsable by dm_world) DFC Installation for Privileged DFC There is more plumbing that must be in place for escalation to work, mostly administrative one-time-only tasks. This is the justification for the additional complication: the content server must know to which DFC installations it may grant escalation right, and to which it must decline escalation rights (for instance, it is wise to decline escalation rights to any unknown instance of Documentum Desktop when the rights are protected) in order to distinguish between DFC installations, each installation must have an identity such identity must be registered with the content server for escalation rights to be granted. DFC D6 enabled for Privileged DFC will, at installation time, create its own PKI credentials [NOT IMPLEMENTED IN BUILD 6] (a private key and a self-signed certificate) distinguished with a unique identity string (at present, a self-generated form of UUID or GUID or similar hash). These credentials are created and kept in a keystore Page 14

15 in the same directory where dfc.properties is also found. The self signed certificate is also shared by publishing it in the Global Registry. In turn, the server [NOT IMPLEMENTED IN BUILD 6] retrieves the self-signed certificate administratively using DA. To enable escalation with role_foo_update for module Foo originating from the DFC installation with identity <mydfc>, the server must associate administratively using DA role_foo_update with <mydfc>. Any other dfc installation with a different identity may not escalate Foo with role_foo_update unless, of course, that different identity is also associated with that role. Runtime Relax. You did your part. Now it s time for DFC and the content server (and your module Foo, of course), to get to work. This is an overview of what happens at runtime, so you may troubleshoot what didn t work (What? It did not work the first time?) with more effectiveness. When a session enabled for privilege escalation is established, two identities are submitted to the content server from the DFC client: the user identity, and the DFC identity. Verification for the user identity is by means of a secret password. Administrative permissions will be checked against those associated with the user identity. Verification of the DFC identity is done using digital signatures: DFC sends, transparently to user code, an identity bundle to the server signed with DFC s private key. The content server verifies the signature using the public certificate of this DFC, formerly retrieved from the repository. Escalation privileges will be checked not to exceed those associated with the identity of the DFC. When the user application retrieves the.jar archives of Foo from the DocBase, a custom class loader checks if a_is_privileged is true and the value in a_privilege_roles and, if the class loader is happy (it will be if you follow all rules), it will give at load time the escalation privilege found in a_privilege_roles to the bytecode classes of Foo. Incidentally, unless you rewrite the class loader, the only manner to test escalation is to retrieve a module from the DocBase and actually load its bytecode via DFC. Two sets of checks happen when Foo executes a privileged block: Java SecurityManager checks DFC escalation checks Another way to look at the same mechanism is to state that DFC allows escalation provided the SecurityManager raises no objections. The Java SecurityManager will inspect all stack activation frames included between the current one (top of the stack, most recent call) and the last frame activated prior to the invocation of the most recent AccessController.doPrivileged() block. (We shall call security context the scope of the inspection.) The SecurityManager will check if any frame lacks a particular permission, in this case role_foo_update. If no lack is found, Page 15

16 then execution will continue. If any stack frame lacks role_foo_update, then execution terminates with an exception. (This is the default behavior of the Java security model.) Since Foo acquires permission (as in java.security.permission) role_foo_update at load time, any bytecode that is part of its.jar also has that permission. However, nobody else (except core functionality of DFC itself) has that permission, as it may be acquired by a module at load time only. In case of normal escalation, this is sufficient. For propagating escalation, it becomes necessary to allow execution for code that may not have been loaded with role_foo_update permission. In this latter case, DFC will take a snapshot of the original security context, and carry out SecurityManager checks against that original snapshot rather than against the actual activated stack frames. Provided all checks succeed, DFC will issue to the content server an enhanced RPC with additional fields including among the rest the privileged role requested (in this case role_foo_update). The content server, on receiving the enhanced RPC, verifies that role_foo_update has been declared (for instance with DA at configuration time) and therefore exists, [NOT IMPLEMENTED IN BUILD 6] that escalation with role_foo_update is allowed for this session (i.e. the id of DFC in the session is associated with role_foo_update), and that the user of the session (as in username/password) has membership in role_foo_update (remember a role is a dynamic group on the server) If all three checks succeed then, after some internal housekeeping, the server executes whatever action the RPC requested using the set union of username administrative permissions and role_foo_update escalated permissions. In other words, overall permissions are a logical OR on the two permission sets: the operation will succeed if there are sufficient (administrative permissions OR escalated permissions). Escalation is stateless. At the end of each RPC the server keeps no state of escalation. The next RPC may not be escalated without also including the enhanced information: Each RPC must include its own privilege enhancements. On the client side, after completion of the code in the privileged block DFC also stops enhancing RPC requests. The session, however, remembers the id of the DFC as well as the identity (username) of the user. How Privileged DFC Works To use Privileged DFC it helps to understand how it works. Without too much detail, here are the building blocks of the operation of Privileged DFC. The following is an informal, but comprehensive laundry list that puts in context the new terms (underlined) that were explained in this tutorial and how-to. First, an important clarification: Module here means either module or TBO, that is a BOF entity guaranteed to be bound to a DocBase. An SBO is in general a global service and is not necessarily bound to a Page 16

17 DocBase. Only BOF code guaranteed to be bound to a DocBase may run with escalation; SBO may not be escalated with Privileged DFC. Attempting the contrary is not allowed and will fail with errors. Before Runtime Write a module, call it Foo (developers do this) o Plan privileged context usage o Design roles as needed o Code privileged blocks with privileged API Create docbase object (with DAB or programmatically) o Create dmc_module object o Set a_is_privileged o Set a_privileged_roles o Save jar to docbase Declare docbase roles (with DAB or programmatically) o RMRole1 o RMRole2 o Define docbase roles granting privileges and permissions to roles (programmatically or with previously existing DA functionality there is no targeted tool support planned for D6.0) o RMRole1: <escalatedwrite> o RMRole2: <creategroup> o Register DFC instance (DFC install) o Create PKI keys in local keystore o Create self-signed certificate o Share certificate to Global Registry o Update dfc.properties Grant rights to use roles to DFC instance (with DA) o Copy DFC certificate to local repository o Update rights database for repository for roles RMRole1, RMRole2 using DFC identity At Runtime (Web App starts) (Browser connects and opens repository) Start session through DFC o Identity for user: DFC sends username/password to server o Identity for DFC: DFC sends authentication bundle to server Server session validates authentication bundle signature using DFC certificate and stores DFC id o Repository validates that this id can use this repository Page 17

18 o Repository validates that this user can use this repository App code invokes module Foo o DFC obtains Foo o DFC validates/verifies Foo if loaded from cache o DFC gets role list from dmc_module and loads Foo with added privileges Code executes privileged block for RMRole1 o DFC/JSM validate that class was loaded with rights to added privileges o DFC invokes execution from content server with privilege-enhanced RPC Server RPC is received with privilege o Server validates that RMRole1 Exists, AND Is allowed for session (i.e. DFC id) [not in build 6], AND Is allowed for username/password All three conditions must be true for success (two in build 6) o Server housekeeping: server adds to dynamic group list Asserted role RMRole1 Any group containing RMRole1 Server request executes e.g. update doc object o Server validates that session may update doc object ACL checks for user usergroup, OR Special escalated write checks At least one of the above conditions must succeed At end of RPC server removes privilege dynamic group inclusions that were stateless and any inherited ones. At end of privileged block DFC stops sending privilege request with RMRole1 Privileged block logic 1. is role propagating? o YES: take snapshot of security context (SOSC) o NO: just continue 2. invoke action o include subcalls and activate their stack frames o subcall can include java function calls, invocations of other privileged modules, invocation of other unprivileged modules 3. if any RPC are involved, check permissions o is role propagating? YES: check against SOSC NO: check against the current security context 4. send RPC with privilege if and only if step 3 is successful Normal or Propagated Escalation? Propagating escalation rights is dangerous. Propagated rights may grant privileges to unsafe, poorly written or downright malicious code. Propagater beware. When should one use propagated escalation? If and only if any alternative is utterly unfeasible; ideally, never. Page 18

19 Alternatives to propagating escalation rights are many. It is possible to design code so that each module is independently privileged with distinct roles. It is possible to create a privileged module that temporarily alters a few selected ACL so that a lesser privileged (or unprivileged) module can complete its tasks, and then restores the original ACL. It is possible to be very creative in devising alternatives. It is. There may be a handful of cases where propagation is the only applicable solution. Be very careful; you are leaving the keys to your home in the middle of the public highway. APPENDIX - Java Policy File $JREHOME/lib/security/java.security The file $JREHOME/lib/security/java.security configures the startup environment for finding the policy files. java.security has several entries: Here are the important ones for the policy files: policy.allowsystemproperty=true policy.url.1=file:$java.home/lib/security/java.policy policy.url.2=file:$user.home/.java.policy There are two default policy files because of the two default entries in java.security. If a different set of policy files is preferred as default, it is necessary to edit the java.security file and change the URLs that are used to identify them. Any number of URLs can be specified, but they must be numbered consecutively beginning with 1. Users can specify any number of policy files on the command line as well. To prevent users from specifying additional policy files, the allowsystemproperty property must be set to false. $java.home/lib/security/java.policy $user.home/.java.policy Java virtual machines can use any number of policy files, but there are two that are used by default as shown above, since they are set in java.security. The global policy file is named $JREHOME/lib/security/java.policy. This file is used by all instances of a virtual machine on a host. In addition, there is a user-specific policy file called.java.policy that may exist in the home directory of the user that starts the virtual machine. The set of permissions given to a program is the union of permissions contained in the global and user-specific policy files. Policy files are simple text files. You can administer them with policytool, or you can edit them by hand. The fiduciary custodian of administrative security must tighten access to java.security and to any and all policy files, and must prevent users from specifying additional policy files if the java startup environment is loose. Page 19

20 A syntax guide for the policy file is available with the JDK documentation. For instance, for Java 1.5.0, the guide is found at.\docs\guide\security\policyfiles.html Page 20