de.schlichtherle.truezip.crypto.raes
Class RaesReadOnlyFile

java.lang.Object
  de.schlichtherle.truezip.rof.AbstractReadOnlyFile
      de.schlichtherle.truezip.rof.DecoratingReadOnlyFile
          de.schlichtherle.truezip.crypto.CipherReadOnlyFile
              de.schlichtherle.truezip.crypto.raes.RaesReadOnlyFile

All Implemented Interfaces:

ReadOnlyFile, Closeable

Direct Known Subclasses:

Type0RaesReadOnlyFile

@NotThreadSafe
@DefaultAnnotation(value=edu.umd.cs.findbugs.annotations.NonNull.class)
public abstract class RaesReadOnlyFile
extends CipherReadOnlyFile

This class implements a ReadOnlyFile in order to provide transparent random read only access to the plain text data which has been encrypted and stored in a file according to the Random Access Encryption Specification (RAES).

To accomodate the transparent random read access feature, RAES specifies a multistep authentication process:

The first step is mandatory and implemented in the constructor of the concrete implementation of this abstract class. For this step only the cipher key and the file length is authenticated, which is fast to process (O(1)).

The second step is optional and must be initiated by the client by calling authenticate(). For this step the entire cipher text is authenticated, which is comparably slow (O(n)). Please note that this step does not require the cipher text to be decrypted first, which features comparably fast processing.

So it is up to the application which level of security it needs to provide: Most applications should always call authenticate() in order to guard against integrity attacks. However, some applications may provide additional (faster) methods for authentication of the pay load, in which case the authentication provided by this class may be safely skipped.

Note that this class implements its own virtual file pointer. Thus, if you would like to access the underlying ReadOnlyFile again after you have finished working with an instance of this class, you should synchronize their file pointers using the pattern as described in the base class DecoratingReadOnlyFile.

Author:

Christian Schlichtherle

See Also:

RaesOutputStream

RaesReadOnlyFile

RaesReadOnlyFile(@CheckForNull
                 ReadOnlyFile rof)

readUByte

static short readUByte(byte[] b,
                       int off)

readUShort

static int readUShort(byte[] b,
                      int off)

readUInt

static long readUInt(byte[] b,
                     int off)

getInstance

public static RaesReadOnlyFile getInstance(File file,
                                           RaesParameters params)
                                    throws FileNotFoundException,
                                           RaesParametersException,
                                           RaesException,
                                           IOException

Creates a new instance of RaesReadOnlyFile.

Parameters:

file - The file to read.

params - The RaesParameters required to access the RAES type actually found in the file. If the run time class of this parameter does not match the required parameter interface according to the RAES type found in the file, but is an instance of the RaesParametersProvider interface, it is used to find the required RAES parameters. This is applied recursively.

Throws:

NullPointerException - If any of the parameters is null.

FileNotFoundException - If the file cannot get opened for reading.

RaesParametersException - If no suitable RAES parameters have been provided or something is wrong with the parameters.

RaesException - If the file is not RAES compatible.

IOException - On any other I/O related issue.

getInstance

public static RaesReadOnlyFile getInstance(ReadOnlyFile rof,
                                           RaesParameters parameters)
                                    throws IOException

Returns a new instance of an RaesReadOnlyFile.

Parameters:

rof - The read only file to read.

parameters - The RaesParameters required to access the RAES type actually found in the file. If the run time class of this parameter does not match the required parameter interface according to the RAES type found in the file, but is an instance of the RaesParametersProvider interface, it's queried to find the required RAES parameters. This algorithm is recursively applied.

Returns:

A new instance of an RaesReadOnlyFile.

Throws:

NullPointerException - If rof is null.

RaesParametersException - If parameters is null or no suitable RAES parameters can be found.

RaesException - If the file is not RAES compatible.

FileNotFoundException - If the file cannot get opened for reading.

IOException - On any other I/O related issue.

findParameters

private static <P extends RaesParameters> P findParameters(Class<P> type,
                                                           @CheckForNull
                                                           RaesParameters parameters)
                                                throws RaesParametersException

Throws:

RaesParametersException

getKeyStrength

public abstract Type0RaesParameters.KeyStrength getKeyStrength()

Returns the key strength which is actually used to decrypt the data of the RAES file.

authenticate

public abstract void authenticate()
                           throws RaesAuthenticationException,
                                  IOException

Authenticates all encrypted data in the read only file. It is safe to call this method multiple times to detect if the file has been tampered with meanwhile.

This is the second, optional step of authentication. The first, mandatory step is to computeMac the cipher key and cipher text length only and has already been successfully completed in the constructor.

Throws:

RaesAuthenticationException - If the computed MAC does not match the MAC declared in the RAES file.

IOException - On any I/O related issue.