org.freshcookies.security.policy
Class SecurityTokenFactory

java.lang.Object
  extended by org.freshcookies.security.policy.SecurityTokenFactory

public class SecurityTokenFactory
extends java.lang.Object

Factory class that dynamically looks up, caches and returns Permission, Principal and CodeSource objects that correspond to supplied strings. The factory will attempt to resolve classes by consulting the parent classloader first, after which it will consult the URLs supplied to the class constructor SecurityTokenFactory(URL[]). This allows the factory to load classes from arbirary JARs, although be warned that this is a potential security hazard and should only be used in carefully controlled situations.

If a SecurityManager is running, the security policy must grant this ProtectionDomain's CodeSource, and all preceding callers, the following permissions:

...where custom-permission-packages and custom-principal-packages are the names of custom Permission and Principal classes loaded from external URLs.

In addition, if the urls parameter passed to the constructor is non-null and has a length of 1 or more, the SecurityManager (if running) will require the ProtectionDomain for this SecurityTokenFactory and all preceding callers to be granted these permissions:

... for all file URLs whose names end in .jar. This is so that the getCodeSource(String) method can successfully resolve and verify any jar file signatures.

None of the methods in this class perform their actions inside doPrivileged blocks, so all SecurityException errors are propagated to callers.


Field Summary
protected static java.util.regex.Pattern PERMISSION_PATTERN
          Pattern that matches permission string e.g., javax.security.auth.AuthPermission "setLoginConfiguration".
protected static java.lang.String REGEX_JAVA_TYPE
          Pattern that matches any valid Java type name, minus the .java or .class suffix.
 
Constructor Summary
SecurityTokenFactory(java.net.URL[] urls)
           Constructs a new instance of this class with a supplied set of supplemental URLs for locating classes.
 
Method Summary
 java.lang.Class findClass(java.lang.String className)
          Looks up and returns a Class matching a supplied fully-qualified type name.
 java.security.CodeSource getCodeSource(java.lang.String path)
           Returns the CodeSource that corresponds to a supplied String, without canonicalizing the path prior to returning it.
 java.security.CodeSource getCodeSource(java.lang.String path, boolean canonicalize)
           Returns the CodeSource corresponding on a specified file path.
 int getCodeSourceCount()
          Returns the number of CodeSource objects cached by this factory since the last time reset() was called.
 java.security.Permission getPermission(java.lang.String permissionString)
           Returns the Permission that corresponds to a supplied String, without canonicalizing the Permission prior to returning it.
 java.security.Permission getPermission(java.lang.String permissionString, boolean canonicalize)
           Returns the Permission that corresponds to a supplied String.
 int getPermissonCount()
          Returns the number of Permission objects cached by this factory since the last time reset() was called.
 java.security.Principal getPrincipal(java.lang.String s)
           Returns the Principal that corresponds to a supplied String containing the name of the Principal class and the Principal's name, separated by spaces.
 int getPrincipalCount()
          Returns the number of Principal objects cached by this factory since the last time reset() was called.
 void reset()
          Flushes the SecurityTokenFactory's caches and resets all counters.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

REGEX_JAVA_TYPE

protected static final java.lang.String REGEX_JAVA_TYPE
Pattern that matches any valid Java type name, minus the .java or .class suffix.

See Also:
Constant Field Values

PERMISSION_PATTERN

protected static final java.util.regex.Pattern PERMISSION_PATTERN
Pattern that matches permission string e.g., javax.security.auth.AuthPermission "setLoginConfiguration".

Constructor Detail

SecurityTokenFactory

public SecurityTokenFactory(java.net.URL[] urls)

Constructs a new instance of this class with a supplied set of supplemental URLs for locating classes. The supplied URLs are used in addition to the parent ClassLoader that instantiated the SecurityTokenFactory.

If the urls parameter passed to the constructor is non-null and has a length of 1 or more, the SecurityManager (if running) will require the ProtectionDomain for this SecurityTokenFactory and all preceding callers to be granted these permissions:

Parameters:
urls - the URLs used for resolving classes
Throws:
java.lang.SecurityException - if a SecurityManager is running and any required permissions were not granted to this Protection Domain and all preceding callers
Method Detail

getPrincipal

public java.security.Principal getPrincipal(java.lang.String s)

Returns the Principal that corresponds to a supplied String containing the name of the Principal class and the Principal's name, separated by spaces. This method will attempt to instantiate the class using reflection, passing the Principal name into the constructor. If the Principal class is not specified, a generic Principal class will be instantiated instead.

Principal Strings look like this:

Parameters:
s - the string specifying the Principal class and name
Returns:
the instantiated Principal
Throws:
java.lang.SecurityException - when the SecurityManager, if running, denies the protection domain of this class (and of all preceding callers):
java.lang.SecurityException - when the SecurityManager, if running, denies the protection domain of this class (and of all preceding callers):
  • java.lang.RuntimePermission "createClassLoader"
  • java.lang.RuntimePermission "accessClassInPackage.java.,javax."
  • java.lang.RuntimePermission "accessClassInPackage.custom-principal-packages"

getPrincipalCount

public int getPrincipalCount()
Returns the number of Principal objects cached by this factory since the last time reset() was called.

Returns:
the number

getPermission

public java.security.Permission getPermission(java.lang.String permissionString)
                                       throws java.lang.ClassNotFoundException

Returns the Permission that corresponds to a supplied String, without canonicalizing the Permission prior to returning it. See getPermission(String, boolean).

Throws:
java.lang.ClassNotFoundException
See Also:
getPermission(String, boolean)

getPermission

public java.security.Permission getPermission(java.lang.String permissionString,
                                              boolean canonicalize)
                                       throws java.lang.ClassNotFoundException

Returns the Permission that corresponds to a supplied String. The String contains the full class name, target and actions, and is formatted exactly like a Java policy file grant statement. Permissions must have at least a target; actions are optional.

Permission strings look like this:

Assuming the Permission string is well-formed, this method always returns a Permission, even if the Permission cannot be located by the classloader. If the Permission class cannot be loaded, the returned Permission will be of type UnresolvedPermission. Permission strings that contain just one argument, for example the class name but no target or actions, will be unresolved.

If the parameter canonicalize is true, the Permission will be canonicalized before it is returned. Specifically, if the Permission is of type FilePermission, its target will be the canonical path. Likewise, SocketPermission local host names 127.0.0.1 and "" will be converted to localhost.

Parameters:
permissionString - the Permission string
canonicalize - whether to canonicalize the Permission before returning it
Returns:
the instantiated Permission
Throws:
java.lang.ClassNotFoundException - if the Permission string is malformed
java.lang.SecurityException - when the SecurityManager, if running, denies the protection domain of this class (and of all preceding callers):
  • java.lang.RuntimePermission "createClassLoader"
  • java.lang.RuntimePermission "accessClassInPackage.java.,javax."
  • java.lang.RuntimePermission "accessClassInPackage.custom-permission-packages"

getPermissonCount

public int getPermissonCount()
Returns the number of Permission objects cached by this factory since the last time reset() was called.

Returns:
the number

getCodeSource

public java.security.CodeSource getCodeSource(java.lang.String path)
                                       throws java.io.IOException,
                                              java.net.MalformedURLException

Returns the CodeSource that corresponds to a supplied String, without canonicalizing the path prior to returning it.

Throws:
java.io.IOException
java.net.MalformedURLException
See Also:
getCodeSource(String, boolean)

getCodeSource

public java.security.CodeSource getCodeSource(java.lang.String path,
                                              boolean canonicalize)
                                       throws java.io.IOException,
                                              java.net.MalformedURLException

Returns the CodeSource corresponding on a specified file path. If the path ends in .jar, this method will attempt to load the Jar file and instantiate the CodeSource with its associated certificates, if possible. To improve performance, CodeSources are cached.

If the parameter canonicalize is true, the path will be canonicalized before it is returned.

Parameters:
path - the absolute path of the jar
canonicalize - whether to canonicalize the Permission before returning it
Returns:
the CodeSource
Throws:
java.io.IOException - if the file cannot be found in the filesystem
java.net.MalformedURLException - if the URL for the CodeSource is malformed
java.lang.SecurityException - when the SecurityManager, if running, denies the protection domain of this class (and of all preceding callers):
  • java.io.FilePermission "path", "read"
  • java.net.NetPermission "specifyStreamHandler"

getCodeSourceCount

public int getCodeSourceCount()
Returns the number of CodeSource objects cached by this factory since the last time reset() was called.

Returns:
the number

findClass

public java.lang.Class findClass(java.lang.String className)
                          throws java.lang.ClassNotFoundException
Looks up and returns a Class matching a supplied fully-qualified type name. The current ClassLoader is tried first; if not found, the classpath supplied in the URLs used to construct this ClassResolver will be tried next.

Parameters:
className - the name of the Class to find
Returns:
the resolved Class
Throws:
java.lang.ClassNotFoundException - if the class cannot be found
java.lang.SecurityException - when the SecurityManager, if running, denies the protection domain of this class (and of all preceding callers) any of these permissions: java.lang.RuntimePermission "getClassLoader", java.lang.RuntimePermission "accessClassInPackage.package-name-of-className".

reset

public void reset()
Flushes the SecurityTokenFactory's caches and resets all counters.