it.necst.grabnrun

Class SecureLoaderFactory

java.lang.Object

it.necst.grabnrun.SecureLoaderFactory

public class SecureLoaderFactory
extends Object

A Factory class that generates instances of classes used to retrieve dynamic code in a secure way at run time.

Author:

Luca Falsina

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_DAYS_BEFORE_CONTAINER_EXPIRACY When a remote container URL is encountered, this field specifies the default time interval, expressed in days, before which a local copy of a remote container, stored in an application-private directory, will be considered fresh and so acceptable to be cached.

Constructor Summary

Constructors

Constructor and Description
SecureLoaderFactory(ContextWrapper parentContextWrapper) Creates a SecureLoaderFactory used to check and generate instances from secure dynamic code loader classes.
SecureLoaderFactory(ContextWrapper parentContextWrapper, int daysBeforeContainerCacheExpiration) This constructor works exactly as the previous one but it also allows to decide the time interval in days before which a local copy of a remote container, stored in an application-private directory, will be considered fresh and so acceptable to be cached.

Method Summary

Methods

Modifier and Type	Method and Description
SecureDexClassLoader	createDexClassLoader(String dexPath, String libraryPath, ClassLoader parent, Map<String,URL> packageNameToCertificateMap) Creates a SecureDexClassLoader that finds interpreted and native code in a set of provided locations (either local or remote via HTTP or HTTPS) in dexPath.
SecureDexClassLoader	createDexClassLoader(String dexPath, String libraryPath, ClassLoader parent, Map<String,URL> packageNameToCertificateMap, boolean performLazyEvaluation) This method returns a SecureDexClassLoader instance in the same way as it is explained in the createDexClassLoader(String, String, ClassLoader, Map).

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_DAYS_BEFORE_CONTAINER_EXPIRACY

public static final int DEFAULT_DAYS_BEFORE_CONTAINER_EXPIRACY

When a remote container URL is encountered, this field specifies the default time interval, expressed in days, before which a local copy of a remote container, stored in an application-private directory, will be considered fresh and so acceptable to be cached.

On the other hand, all of those containers, whose life time is greater than this field value, will be immediately erased from the device storage in stead of being cached.

You can change this duration by generating the SecureLoaderFactory instance with SecureLoaderFactory#SecureLoaderFactory(android.content.ContextWrapper, int).

See Also:

Constant Field Values

Constructor Detail

SecureLoaderFactory

public SecureLoaderFactory(ContextWrapper parentContextWrapper)

Creates a SecureLoaderFactory used to check and generate instances from secure dynamic code loader classes.

It requires a ContextWrapper (i.e. the launching activity) which should be used to manage and retrieve internal directories of the application.

Parameters:

parentContextWrapper - The content wrapper coming from the launching Activity.

SecureLoaderFactory

public SecureLoaderFactory(ContextWrapper parentContextWrapper,
                   int daysBeforeContainerCacheExpiration)

This constructor works exactly as the previous one but it also allows to decide the time interval in days before which a local copy of a remote container, stored in an application-private directory, will be considered fresh and so acceptable to be cached.

If a negative value is provided for the second parameter, SecureLoaderFactory will be instantiated with the time interval in days equal to DEFAULT_DAYS_BEFORE_CONTAINER_EXPIRACY.

Parameters:

parentContextWrapper - The content wrapper coming from the launching Activity.

daysBeforeContainerCacheExpiration - The non negative value of days for which a local copy of a remote container imported into an application private folder is considered fresh and so acceptable to be cached.

Method Detail

createDexClassLoader

public SecureDexClassLoader createDexClassLoader(String dexPath,
                                        String libraryPath,
                                        ClassLoader parent,
                                        Map<String,URL> packageNameToCertificateMap)

Creates a SecureDexClassLoader that finds interpreted and native code in a set of provided locations (either local or remote via HTTP or HTTPS) in dexPath. Interpreted classes are found in a set of DEX files contained in Jar or Apk files and stored into an application-private, writable directory.

Before executing one of these classes the signature of the target class is verified against the certificate associated with its package name. Certificates location are provided by filling appropriately packageNameToCertificateMap; each package name must be linked with the remote location of the certificate that should be used to validate all the classes of that package. It's important that each one of these locations uses HTTPS as its protocol; otherwise this choice will be enforced! If a class package name do not match any of the provided entries in the map, certificate location will be constructed by simply reverting package name and transforming it into a web-based URL using HTTPS.

Note that this method returns null if no matching Jar or Apk file is found at the provided dexPath parameter; otherwise a SecureDexClassLoader instance is returned.

Dynamic class loading with the returned SecureDexClassLoader will fail whether at least one of these conditions is not accomplished: target class is not found in dexPath or is in a missing remote container (i.e. Internet connectivity is not present), missing or invalid (i.e. expired) certificate is associated with the package name of the target class, target class signature check fails against the associated certificate.

Parameters:

dexPath - the list of jar/apk files containing classes and resources; these paths could be either local URLs pointing to a location in the device or URLs that links to a resource stored in the web via HTTP/HTTPS. In the latter case, if Internet connectivity is available, the resource will be imported in a private-application directory before being used.

libraryPath - the list of directories containing native libraries; it may be null.

parent - the parent class loader.

packageNameToCertificateMap - a map that couples each package name to a URL which contains the certificate that must be used to validate all the classes that belong to that package before launching them at run time. Please notice that any URL in this map using HTTP protocol will be enforced to use HTTPS in stead.

Returns:

a SecureDexClassLoader object which can be used to load dynamic code securely and uses a Eager strategy for container signature verification.

createDexClassLoader

public SecureDexClassLoader createDexClassLoader(String dexPath,
                                        String libraryPath,
                                        ClassLoader parent,
                                        Map<String,URL> packageNameToCertificateMap,
                                        boolean performLazyEvaluation)

This method returns a SecureDexClassLoader instance in the same way as it is explained in the createDexClassLoader(String, String, ClassLoader, Map). In addition it is possible to specify the mode in which the signature verification process will be carried.

In particular by setting the performLazyEvaluation parameter on true, a lazy verification process will be chosen. This means that the signature of the single container associated with the target class will be evaluated only when SecureDexClassLoader.loadClass(String) will be invoked . If this check succeeds the target class will be loaded.

On the other hand, by setting the parameter performLazyEvaluation to false an eager evaluation will be carried out. This means that before returning this object, the signature verification procedure will be carried out on all the provided containers in a CONCURRENT way and all of those that do not succeed in the process will be blocked from loading their classes in the following loadClass() method calls.

The use of one mode in stead of the other is merely a performance-related choice. If you do not care that much about it, just invoke createDexClassLoader(String, String, ClassLoader, Map) which does not require to provide the performLazyEvaluation parameter and it will perform an Eager evaluation. Otherwise as a general guideline, prefer the lazy mode whenever you think that you won't need to load classes from all the provided containers.

Parameters:

dexPath - the list of jar/apk files containing classes and resources; these paths could be either local URLs pointing to a location in the device or URLs that links to a resource stored in the web via HTTP/HTTPS. In the latter case, if Internet connectivity is available, the resource will be imported in a private-application directory before being used.

libraryPath - the list of directories containing native libraries; it may be null.

parent - the parent class loader.

packageNameToCertificateMap - a map that couples each package name to a URL which contains the certificate that must be used to validate all the classes that belong to that package before launching them at run time. Please notice that any URL in this map using HTTP protocol will be enforced to use HTTPS in stead.

performLazyEvaluation - the mode in which the verification will be handled. True for lazy verification; false for the eager one.

Returns:

a SecureDexClassLoader object which can be used to load dynamic code securely and uses a either Lazy or an Eager strategy for container signature verification depending on the last parameter provided to this constructor.