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, AutoCloseable

@NotThreadSafe
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

Field Summary

Fields inherited from class de.schlichtherle.truezip.rof.DecoratingReadOnlyFile

delegate

Method Summary

Modifier and Type	Method and Description
abstract void	authenticate() Authenticates all encrypted data in this read only file.
static RaesReadOnlyFile	getInstance(File file, RaesParameters param) Returns a new RaesReadOnlyFile.
static RaesReadOnlyFile	getInstance(ReadOnlyFile rof, RaesParameters param) Returns a new RaesReadOnlyFile.
abstract Type0RaesParameters.KeyStrength	getKeyStrength() Returns the key strength which is actually used to decrypt the data of the RAES file.

Methods inherited from class de.schlichtherle.truezip.crypto.CipherReadOnlyFile

close, computeMac, getFilePointer, init, length, read, read, seek

Methods inherited from class de.schlichtherle.truezip.rof.DecoratingReadOnlyFile

toString

Methods inherited from class de.schlichtherle.truezip.rof.AbstractReadOnlyFile

read, readFully, readFully

Methods inherited from class java.lang.Object

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

Method Detail

authenticate

public abstract void authenticate()
                           throws IOException

Authenticates all encrypted data in this 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 compute the cipher key and cipher text length only and must already have 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.

getInstance

@CreatesObligation
public static RaesReadOnlyFile getInstance(File file,
                                                              @Nullable
                                                              RaesParameters param)
                                                       throws IOException

Returns a new RaesReadOnlyFile.

Parameters:

file - The file to open for reading the ciphered data.

param - 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:

FileNotFoundException - If the file cannot get opened for reading.

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

RaesException - If the file is not RAES compatible.

IOException - on any I/O error.

getInstance

@CreatesObligation
public static RaesReadOnlyFile getInstance(@WillCloseWhenClosed
                                                              ReadOnlyFile rof,
                                                              @CheckForNull
                                                              RaesParameters param)
                                                       throws IOException

Returns a new RaesReadOnlyFile.

Parameters:

rof - the read only file to decorate for reading the ciphered data.

param - 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 RaesReadOnlyFile.

Throws:

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

RaesException - If the file is not RAES compatible.

IOException - on any I/O error.

getKeyStrength

public abstract Type0RaesParameters.KeyStrength getKeyStrength()

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