com.entrust.toolkit.security.fips

Class JarAuthenticator

java.lang.Object

com.entrust.toolkit.security.fips.JarAuthenticator

public class JarAuthenticator
extends java.lang.Object

This class provides the ability to MAC Protect and Authenticate JAR files.

When used for MAC protection, a MAC is calculated over all non-meta data in the JAR file. The MAC value is then stored in the manifest under the 'MACValue' attribute. Once MAC protected, this MAC value can be later used to prove that the JAR file has not since been modified (authenticate).

When use for MAC authentication, a MAC is re-calculated over all non-meta data in the JAR and compared against the value found in the manifest under the 'MACValue' attribute. If the values match, the JAR file has been authenticated; otherwise it has been modified since originally MACed, and authentication fails.

This class is already used by the FIPS module to provide the required authentication of all security related classes. It is provided here as a utility for people who wish to add FIPS-approved Authentication for additional JAR files that they may create.

FIPS 140-2:

This class is part of the Toolkit's FIPS 140-2 cryptographic module and contains APIs that are considered part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; refer to the API documentation for further details

Constructor Summary

Constructors

Constructor and Description
JarAuthenticator() The default constructor.
JarAuthenticator(java.lang.String macAlgorithm) This creates a JarAuthenticator that uses the specified MACing algorithm - any MAC algorithm that is provided by the Entrust provider is supported.

Method Summary

Modifier and Type	Method and Description
boolean	authenticate(java.util.jar.JarFile jar, byte[] key) Authenticates a MAC protected JAR file.
static java.lang.String	convertToJarProtocol(java.lang.String url, TraceLog traceLog) Converts to jar protocol any provided URL string that resembles "some kind of" URL to a jar.
java.lang.String	getMacAlgorithm() Returns the MAC algorithm that this JarAuthenticator uses for both MAC creation and authentication.
void	mac(java.util.jar.JarFile jar, byte[] key) MAC protects a JAR file.
void	setMacAlgorithm(java.lang.String macAlgorithm) Sets the MAC algorithm that this JarAuthenticator will use for both MAC creation and authentication - any MAC algorithm that is provided by the Entrust provider is supported.

Methods inherited from class java.lang.Object

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

Constructor Detail

JarAuthenticator

public JarAuthenticator()

The default constructor. It creates a JarAuthenticator that uses the 'DESede' MAC algorithm.

The DESede MAC algorithm is based on the Data Authentication Algorithm specified in FIPS 113, using the DESede Symmetric Cipher instead of DES (DESede is recommended instead of DES). This algorithm is FIPS approved.

FIPS 140-2:

FIPS Service: Initialization

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call)
• status output interface (exceptions)

Throws:

java.lang.SecurityException - [FIPS 140-2 status output] thrown if the Entrust provider has not been installed

JarAuthenticator

public JarAuthenticator(java.lang.String macAlgorithm)

This creates a JarAuthenticator that uses the specified MACing algorithm - any MAC algorithm that is provided by the Entrust provider is supported.

For the MACs that this class creates/authenticates to be FIPS approved, the 'DES' or 'DESede' MAC algorithm must be used. Although this class allows the use of other MAC algorithms, this is not FIPS approved usage.

FIPS 140-2:

FIPS Service: Initialization

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call, parameters)
• status output interface (exceptions)

Parameters:

macAlgorithm - [FIPS 140-2 control input] the MAC algorithm

Throws:

java.lang.IllegalArgumentException - [FIPS 140-2 status output] thrown if the MAC algorithm is null, or not supported

java.lang.SecurityException - [FIPS 140-2 status output] thrown if the Entrust provider has not been installed

Method Detail

convertToJarProtocol

public static java.lang.String convertToJarProtocol(java.lang.String url,
                                                    TraceLog traceLog)

Converts to jar protocol any provided URL string that resembles "some kind of" URL to a jar.

Examples:

1. "wsjar:file:/C:/entbase.jar!/" will be converted to "jar:file:/C:/entbase.jar!/"
2. "jrun://localvm/.../entbase.jar/" will not be changed.
3. "zip:/path/myjar.jar!/" converts to "jar:file:/path/myjar.jar!/"
4. "zip:C:/path/myjar.jar!/" converts to "jar:file:/C:/path/myjar.jar!/"
5. "jar:http://path/myjar.jar!/" will not be changed.
6. "jar:file:/C:/path/myjar.jar!/" will not be changed.

Note: The URL must reference a jar, not a particular class inside that jar.

FIPS 140-2:

This API is not part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; it is a helper utility that does not perform any cryptographic function

Parameters:

url - a url string

traceLog - the debug trace log that debug information will be written to

Returns:

the converted url string

setMacAlgorithm

public void setMacAlgorithm(java.lang.String macAlgorithm)

Sets the MAC algorithm that this JarAuthenticator will use for both MAC creation and authentication - any MAC algorithm that is provided by the Entrust provider is supported.

For the MACs this class creates/authenticates to be FIPS approved, the 'DES' or 'DESede' MAC algorithm must be used. Although this class allows the use of other MAC algorithms, this is not FIPS approved usage.

FIPS 140-2:

FIPS Service: Modify Object

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call, parameters)
• status output interface (exceptions)

Parameters:

macAlgorithm - [FIPS 140-2 control input] the MAC algorithm

Throws:

java.lang.IllegalArgumentException - [FIPS 140-2 status output] thrown if the MAC algorithm is null, or not supported

java.lang.SecurityException - [FIPS 140-2 status output] thrown if the Entrust provider has not been installed

getMacAlgorithm

public java.lang.String getMacAlgorithm()

Returns the MAC algorithm that this JarAuthenticator uses for both MAC creation and authentication.

FIPS 140-2:

FIPS Service: Query Object

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call)
• status output interface (exceptions, return value)

Returns:

[FIPS 140-2 status output] the MAC algorithm

mac

public void mac(java.util.jar.JarFile jar,
                byte[] key)
         throws java.io.IOException,
                java.security.InvalidKeyException

MAC protects a JAR file. If the indicated JAR file exists, a MAC is calculated over a selected group of files contained within the JAR, using the provided key.

The group of files that the MAC is calculated over consists of all files in the JAR with the exception of the any meta-data.

The MAC value is then written into the manifest as an attribute with the name 'MACValue'. The process of writing the manifest actually consists of creating a new JAR file with the updated manifest, deleting the existing JAR file, and renaming to new JAR to the old one. As a result, following a call to this method, the JAR file parameter will no longer reference a valid jar file.

FIPS 140-2:

FIPS Service: MAC Generation/Verification

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call, parameters)
• data input interface (parameters)
• status output interface (exceptions)

Parameters:

jar - [FIPS 140-2 control input] the JAR file to be MAC protected

key - [FIPS 140-2 data input] [FIPS 140-2 CSP] the key that is used to create the MAC

Throws:

java.lang.IllegalArgumentException - [FIPS 140-2 status output] thrown if any of the parameters are null

java.io.IOException - [FIPS 140-2 status output] thrown if errors occur while reading/writing the JAR file

java.security.InvalidKeyException - [FIPS 140-2 status output] thrown if the key is not valid for the MAC algorithm

authenticate

public boolean authenticate(java.util.jar.JarFile jar,
                            byte[] key)
                     throws java.io.IOException,
                            java.security.InvalidKeyException

Authenticates a MAC protected JAR file. If the indicated JAR file exists, a MAC is recalculated over a selected group of files contained within the JAR, using the provided key.

The group of files being authenticated consists of all files in the JAR with the exception of any meta data.

The original MAC value is read from the manifest and compared with the recalculated value. If the values are identical, then the JAR has been authenticated and true is returned; otherwise false is returned.

FIPS 140-2:

FIPS Service: MAC Generation/Verification

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 user role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call, parameters)
• data input interface (parameters)
• status output interface (exceptions)

Parameters:

jar - [FIPS 140-2 control input] the JAR file to be authenticated

key - [FIPS 140-2 data input] [FIPS 140-2 CSP] the key that is used to create the MAC

Throws:

java.lang.IllegalArgumentException - [FIPS 140-2 status output] thrown if any of the parameters are null

java.io.IOException - [FIPS 140-2 status output] thrown if errors occur while reading the JAR file

java.security.InvalidKeyException - [FIPS 140-2 status output] thrown if the key is not valid for the MAC algorithm

Fips140ErrorStateException - [FIPS 140-2 status output] thrown if the Toolkit is not allowed to perform cryptographic operations