net.nicholaswilliams.java.licensing

Class LicenseManager

java.lang.Object

net.nicholaswilliams.java.licensing.LicenseManager

public final class LicenseManager
extends Object

This class manages licenses in the client application. All interaction with the license manager done from the client application should go through here. Before getting the manager instance for the first time, relevant properties should be set in LicenseManagerProperties. The values in this class will be used to instantiate the license manager. After setting all the necessary properties there, one can retrieve an instance using getInstance(). Be sure to set all the properties first; once getInstance() is called for the first time, any changes to LicenseManagerProperties will be ignored.

The license manager maintains a cache of license objects, which cannot be disabled entirely. When initializing the license manager, a maximum cache object age is specified in minutes. If any value less than 1 minute is specified, then the maximum cache object age is set to 10 seconds by default. The advantage of using a longer cache age is increased client application performance, especially with multi-tenant SaaS applications with high load. The disadvantage is decreased security, although that security concern is almost completely mitigated by the presence of the LicenseSecurityManager.

This security manager is one of the most integral pieces to the license manager. It prevents reflection attacks from disabling or compromising the security features in this product. It is instantiated when createInstance is called and cannot be disabled. For more information on how it works, see the JavaDoc for the LicenseSecurityManager.

Since:

1.0.0

Version:

1.0.2

Author:

Nick Williams

See Also:

LicenseSecurityManager, InsecureEnvironmentException

Method Summary

Methods

Modifier and Type	Method and Description
void	clearLicenseCache() Clears the cache of licenses, forcing all license data to be re-retrieved from the license data provider on the next call to getLicense(Object).
License	decryptAndVerifyLicense(SignedLicense signedLicense) This method verifies the signed license object's signature, then decrypts the signed license and returns the decrypted license.
static LicenseManager	getInstance() Returns the license manager instance.
License	getLicense(Object context) If the license has already been cached for the specified context (account, client, etc.) and the cache has not become stale (its age has not surpassed the cache time limitation configured for this manager), this returns the cached license.
boolean	hasLicenseForAllFeatures(Object context, FeatureObject... features) Checks whether the license assigned to the specified context is licensed to use all of the features specified.
boolean	hasLicenseForAllFeatures(Object context, String... featureNames) Checks whether the license assigned to the specified context is licensed to use all of the features specified.
boolean	hasLicenseForAnyFeature(Object context, FeatureObject... features) Checks whether the license assigned to the specified context is licensed to use any of the features specified.
boolean	hasLicenseForAnyFeature(Object context, String... featureNames) Checks whether the license assigned to the specified context is licensed to use any of the features specified.
boolean	hasLicenseForFeature(Object context, FeatureObject feature) Checks whether the license assigned to the specified context is licensed to use the feature specified.
boolean	hasLicenseForFeature(Object context, String featureName) Checks whether the license assigned to the specified context is licensed to use the feature specified.
boolean	hasLicenseForFeatures(Object context, AnnotatedElement target) Checks whether the license assigned to the specified context is licensed to use the feature(s) in the FeatureRestriction annotation value, if the target is annotated with that annotation.
boolean	hasLicenseForFeatures(Object context, FeatureRestriction annotation) Checks whether the license assigned to the specified context is licensed to use the feature(s) in the annotation value.
void	validateLicense(License license) This method calls LicenseValidator.validateLicense(License) on the validator that was provided, if one was provided.
void	verifyLicenseSignature(SignedLicense signedLicense) This method verifies the signed license object's signature.

Methods inherited from class java.lang.Object

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

Method Detail

getInstance

public static LicenseManager getInstance()

Returns the license manager instance. Before this method can be called the first time, all of the parameters must bet set in LicenseManagerProperties. See the documentation for that class for more details.

Returns:

the license manager instance.

Throws:

IllegalArgumentException - if licenseProvider, publicKeyPasswordProvider or publicKeyDataProvider are null.

InsecureEnvironmentException - if the LicenseSecurityManager cannot be instantiated

See Also:

for more information on the security features that protect the license manager

validateLicense

public final void validateLicense(License license)
                           throws InvalidLicenseException

This method calls LicenseValidator.validateLicense(License) on the validator that was provided, if one was provided.

Parameters:

license - The license to validate

Throws:

InvalidLicenseException - when the license is invalid for any reason.

ExpiredLicenseException - when the license is expired.

hasLicenseForFeature

public final boolean hasLicenseForFeature(Object context,
                           String featureName)
                                   throws InvalidLicenseException

Checks whether the license assigned to the specified context is licensed to use the feature specified.

Throws the same exceptions as getLicense(Object) and for the same reasons.

Parameters:

context - The context (account, client, etc.) for which to check the feature(s) against its license

featureName - The feature (or features) to check against the license

Returns:

true if the license exists and has this feature enabled, false otherwise.

Throws:

InvalidLicenseException - when the license is invalid for any reason.

ExpiredLicenseException - when the license is expired.

hasLicenseForFeature

public final boolean hasLicenseForFeature(Object context,
                           FeatureObject feature)
                                   throws InvalidLicenseException

Checks whether the license assigned to the specified context is licensed to use the feature specified.

Throws the same exceptions as getLicense(Object) and for the same reasons.

Parameters:

context - The context (account, client, etc.) for which to check the feature(s) against its license

feature - The feature (or features) to check against the license

Returns:

true if the license exists and has this feature enabled, false otherwise.

Throws:

InvalidLicenseException - when the license is invalid for any reason.

ExpiredLicenseException - when the license is expired.

hasLicenseForAnyFeature

public final boolean hasLicenseForAnyFeature(Object context,
                              String... featureNames)
                                      throws InvalidLicenseException

Checks whether the license assigned to the specified context is licensed to use any of the features specified.

Throws the same exceptions as getLicense(Object) and for the same reasons.

Parameters:

context - The context (account, client, etc.) for which to check the feature(s) against its license

featureNames - The feature (or features) to check against the license

Returns:

true if the license exists and has this feature enabled, false otherwise.

Throws:

InvalidLicenseException - when the license is invalid for any reason.

ExpiredLicenseException - when the license is expired.

hasLicenseForAnyFeature

public final boolean hasLicenseForAnyFeature(Object context,
                              FeatureObject... features)
                                      throws InvalidLicenseException

Checks whether the license assigned to the specified context is licensed to use any of the features specified.

Throws the same exceptions as getLicense(Object) and for the same reasons.

Parameters:

context - The context (account, client, etc.) for which to check the feature(s) against its license

features - The feature (or features) to check against the license

Returns:

true if the license exists and has this feature enabled, false otherwise.

Throws:

InvalidLicenseException - when the license is invalid for any reason.

ExpiredLicenseException - when the license is expired.

hasLicenseForAllFeatures

public final boolean hasLicenseForAllFeatures(Object context,
                               String... featureNames)
                                       throws InvalidLicenseException

Checks whether the license assigned to the specified context is licensed to use all of the features specified.

Throws the same exceptions as getLicense(Object) and for the same reasons.

Parameters:

context - The context (account, client, etc.) for which to check the feature(s) against its license

featureNames - The feature (or features) to check against the license

Returns:

true if the license exists and has this feature enabled, false otherwise.

Throws:

InvalidLicenseException - when the license is invalid for any reason.

ExpiredLicenseException - when the license is expired.

hasLicenseForAllFeatures

public final boolean hasLicenseForAllFeatures(Object context,
                               FeatureObject... features)
                                       throws InvalidLicenseException

Checks whether the license assigned to the specified context is licensed to use all of the features specified.

Throws the same exceptions as getLicense(Object) and for the same reasons.

Parameters:

context - The context (account, client, etc.) for which to check the feature(s) against its license

features - The feature (or features) to check against the license

Returns:

true if the license exists and has this feature enabled, false otherwise.

Throws:

InvalidLicenseException - when the license is invalid for any reason.

ExpiredLicenseException - when the license is expired.

hasLicenseForFeatures

public final boolean hasLicenseForFeatures(Object context,
                            FeatureRestriction annotation)
                                    throws InvalidLicenseException

Checks whether the license assigned to the specified context is licensed to use the feature(s) in the annotation value.

Throws the same exceptions as getLicense(Object) and for the same reasons.

Parameters:

context - The context (account, client, etc.) for which to check the feature(s) against its license

annotation - The annotation object whose value(s) is(are) the feature(s) to check against the license

Returns:

true if the license exists and has this feature(s) enabled, false otherwise.

Throws:

InvalidLicenseException - when the license is invalid for any reason.

ExpiredLicenseException - when the license is expired.

hasLicenseForFeatures

public final boolean hasLicenseForFeatures(Object context,
                            AnnotatedElement target)
                                    throws InvalidLicenseException

Checks whether the license assigned to the specified context is licensed to use the feature(s) in the FeatureRestriction annotation value, if the target is annotated with that annotation.

Throws the same exceptions as getLicense(Object) and for the same reasons.

Parameters:

context - The context (account, client, etc.) for which to check the feature(s) against its license

target - The target (a package reflection object, class reflection object or method reflection object) to check for the FeatureRestriction annotation and check its value against the license

Returns:

false if the license does not exist, true if the target is not annotated with FeatureRestriction and, if it is annotated, true if the feature(s) is(are) licensed or false if the feature(s) is(are) not licensed

Throws:

InvalidLicenseException - when the license is invalid for any reason.

ExpiredLicenseException - when the license is expired.

getLicense

public final License getLicense(Object context)
                         throws KeyNotFoundException,
                                AlgorithmNotSupportedException,
                                InappropriateKeySpecificationException,
                                InappropriateKeyException,
                                CorruptSignatureException,
                                InvalidSignatureException,
                                FailedToDecryptException

If the license has already been cached for the specified context (account, client, etc.) and the cache has not become stale (its age has not surpassed the cache time limitation configured for this manager), this returns the cached license. If it has not been cached or the cache is stale, this retrieves the license from the store, decrypts it, deserializes it, checks its signature and, if everything is kosher, caches and returns the license.

This method takes precautions to ensure that the cache is not tampered with using reflection. However, it is not infallible. For extra security, one could configure this manager with a 10-second cache (zero cache time limit in minutes), but we highly recommend implementing caching in the license data provider: the signature checking process is time consuming (on the order of hundreds of milliseconds, and could happen multiple times per action) and the added overhead of retrieving the license from the store every time could bring an application to its knees.

Parameters:

context - The context (account, client, etc.) for which to retrieve the license object

Returns:

the requested license object, or null if none exists.

Throws:

KeyNotFoundException - if the public key data could not be found.

AlgorithmNotSupportedException - if the signature algorithm is not supported on this system.

InappropriateKeySpecificationException - if an inappropriate key specification is provided.

InappropriateKeyException - if there is a problem initializing the verification mechanism with the public key.

CorruptSignatureException - if the signature data has been corrupted (most likely tampered with).

InvalidSignatureException - if the signature is invalid (most likely tampered with).

FailedToDecryptException - if the license or signature could not be decrypted.

ObjectTypeNotExpectedException - if the license data was tampered with.

clearLicenseCache

public final void clearLicenseCache()

Clears the cache of licenses, forcing all license data to be re-retrieved from the license data provider on the next call to getLicense(Object).

verifyLicenseSignature

public final void verifyLicenseSignature(SignedLicense signedLicense)
                                  throws AlgorithmNotSupportedException,
                                         InappropriateKeyException,
                                         CorruptSignatureException,
                                         InvalidSignatureException

This method verifies the signed license object's signature. It throws an exception if the signature is invalid. Normally you will not need to call this method; all of the other methods in this class call this method at some point or another in one way or another (specifically by way of getLicense(Object)). This is a convenience method useful for verifying the signature of an individual license without going through all of the retrieval and caching mechanisms normally used when calling getLicense(Object).

Parameters:

signedLicense - The signed license object to verify

Throws:

AlgorithmNotSupportedException - if the signature algorithm is not supported on this system.

InappropriateKeyException - if there is a problem initializing the verification mechanism with the public key.

CorruptSignatureException - if the signature data has been corrupted (most likely tampered with).

InvalidSignatureException - if the signature is invalid (most likely tampered with).

decryptAndVerifyLicense

public final License decryptAndVerifyLicense(SignedLicense signedLicense)

This method verifies the signed license object's signature, then decrypts the signed license and returns the decrypted license. It throws an exception if the signature is invalid. Normally you will not need to call this method; all of the other methods in this class call this method at some point or another in one way or another (specifically by way of getLicense(Object)). This is a convenience method useful for verifying the signature of and interpreting an individual license without going through all of the retrieval and caching mechanisms normally used when calling getLicense(Object).

Parameters:

signedLicense - The signed license object to verify

Returns:

the decrypted license object.

Throws:

AlgorithmNotSupportedException - if the signature algorithm is not supported on this system.

InappropriateKeyException - if there is a problem initializing the verification mechanism with the public key.

CorruptSignatureException - if the signature data has been corrupted (most likely tampered with).

InvalidSignatureException - if the signature is invalid (most likely tampered with).

FailedToDecryptException - if the license could not be decrypted.