10.7. Running JBoss with a Java 2 security manager

By default the JBoss server does not start with a Java 2 security manager. If you want to restrict privileges of code using Java 2 permissions you need to configure the JBoss server to run under a security manager. This is done by configuring the Java VM options in the run.bat or run.sh scripts in the JBoss server distribution bin directory. The two required VM options are as follows:
  • java.security.manager: This is used without any value to specify that the default security manager should be used. This is the preferred security manager. You can also pass a value to the java.security.manager option to specify a custom security manager implementation. The value must be the fully qualified class name of a subclass of java.lang.SecurityManager. This form specifies that the policy file should augment the default security policy as configured by the VM installation.
  • java.security.policy: This is used to specify the policy file that will augment the default security policy information for the VM. This option takes two forms: java.security.policy=policyFileURL and java.security.policy==policyFileURL. The first form specifies that the policy file should augment the default security policy as configured by the VM installation. The second form specifies that only the indicated policy file should be used. The policyFileURL value can be any URL for which a protocol handler exists, or a file path specification.
Both the run.bat and run.sh start scripts reference an JAVA_OPTS variable which you can use to set the security manager properties.
The next element of Java security is establishing the allowed permissions. You define the permissions by creating a server.policy file in the $JBOSS_HOME/bin/directory. In this file you declare the following grant statement: 
grant signedBy "jboss" { 
   permission java.security.AllPermission; 
};
This statement declares that all code signed by JBoss is trusted. To import the public key to your keystore, follow Procedure 10.1, “Activate Java Security Manager”
The current set of JBoss specific java.lang.RuntimePermissions are described below.
org.jboss.security.SecurityAssociation.getPrincipalInfo
Provides access to the org.jboss.security.SecurityAssociation getPrincipal() and getCredentials() methods. The risk involved with using this runtime permission is the ability to see the current thread caller and credentials.
org.jboss.security.SecurityAssociation.setPrincipalInfo
Provides access to the org.jboss.security.SecurityAssociation setPrincipal() and setCredentials() methods. The risk involved with using this runtime permission is the ability to set the current thread caller and credentials.
org.jboss.security.SecurityAssociation.setServer
Provides access to the org.jboss.security.SecurityAssociation setServer method. The risk involved with using this runtime permission is the ability to enable or disable multithread storage of the caller principal and credential.
org.jboss.security.SecurityAssociation.setRunAsRole
Provides access to the org.jboss.security.SecurityAssociation pushRunAsRole and popRunAsRole methods. The risk involved with using this runtime permission is the ability to change the current caller run-as role principal.

Procedure 10.1. Activate Java Security Manager

Follow this procedure to correctly configure the JSM for secure, production-ready operation. This procedure is only required while configuring your server for the first time. In this procedure, $JAVA_HOME refers to the installation directory of the JRE.

  1. Import public key to keystore

    Execute the following command:
    Linux

    [home]$ sudo $JAVA_HOME/bin/keytool -import  -alias jboss -file JBossPublicKey.RSA -keystore $JAVA_HOME/jre/lib/security/cacerts

    Windows

    C:\> $JAVA_HOME\bin\keytool -import  -alias jboss -file JBossPublicKey.RSA -keystore $JAVA_HOME\jre\lib\security\cacerts

  2. Verify key signature

    Execute the following command in the terminal.

    Note

    The default JVM Keystore password is changeit. 
    $ keytool -list
Enter keystore password:  

Keystore type: JKS
Keystore provider: SUN

Your keystore contains 2 entries

jboss, Aug 12, 2009, trustedCertEntry,
Certificate fingerprint (MD5): 93:F2:F1:8B:EF:8A:E0:E3:D0:E7:69:BC:69:96:29:C1
jbosscodesign2009, Aug 12, 2009, trustedCertEntry,
Certificate fingerprint (MD5): 93:F2:F1:8B:EF:8A:E0:E3:D0:E7:69:BC:69:96:29:C1

  3. Specify additional JAVA_OPTS

    Linux

    Ensure the following block is present in the $JBOSS_HOME/bin/run.conf file. 

    ## Specify the Security Manager options
JAVA_OPTS="$JAVA_OPTS -Djava.security.manager -Djava.security.policy==$DIRNAME/server.policy.cert 
-Djava.protocol.handler.pkgs=org.jboss.handlers.stub 
-Djava.security.debug=access:failure 
-Djboss.home.dir=$DIRNAME/../ 
-Djboss.server.home.dir=$DIRNAME/../server/default/"
    Windows

    Ensure the following block is present in the $JBOSS_HOME\bin\run.conf.bat file. 

    rem # Specify the Security Manager options
set "JAVA_OPTS=%JAVA_OPTS% -Djava.security.manager
-Djava.security.policy==%DIRNAME%\server.policy.cert 
-Djava.protocol.handler.pkgs=org.jboss.handlers.stub 
-Djava.security.debug=access:failure 
-Djboss.home.dir=%DIRNAME%/../ 
-Djboss.server.home.dir=%DIRNAME%/../server/default/"

  4. Start the server

    Start JBoss EAP using the run.sh or run.bat (Windows) script.
A number of Java debugging flags are available to assist you in determining how the security manager is using your security policy file, and what policy files are contributing permissions. Running the VM as follows shows the possible debugging flag settings: 
[bin]$ java -Djava.security.debug=help

all            turn on all debugging
access         print all checkPermission results
combiner       SubjectDomainCombiner debugging
configfile     JAAS ConfigFile loading
configparser   JAAS ConfigFile parsing
gssloginconfig GSS LoginConfigImpl debugging
jar            jar verification
logincontext   login context results
policy         loading and granting
provider       security provider debugging
scl            permissions SecureClassLoader assigns

The following can be used with access:

stack         include stack trace
domain        dump all domains in context
failure       before throwing exception, dump stack
              and domain that didn't have permission

The following can be used with stack and domain:

permission=<classname>
              only dump output if specified permission
              is being checked
codebase=<URL>
              only dump output if specified codebase
              is being checked
Running with -Djava.security.debug=all provides the most output, but the output volume is acutely verbose. This might be a good place to start if you don't understand a given security failure at all. For less verbose output that will still assist with debugging permission failures, use -Djava.security.debug=access,failure.