@DefaultAnnotation(value=edu.umd.cs.findbugs.annotations.NonNull.class)

Package de.schlichtherle.truezip.crypto.raes

Reads and writes files according to the Random Access Encryption Specification (RAES).

See: Description

Interface Summary

Interface	Description
RaesParameters	A marker interface for RAES parameters.
RaesParametersProvider	These RaesParameters delegate to some other instance of a sibling interface or itself in order to locate the parameters required to read or write a RAES file of a given type.
Type0RaesParameters	The parameters of this interface are used with RAES type 0 files.

Class Summary

Class	Description
RaesOutputStream	An OutputStream to produce a file with data ecnrypted according to the Random Access Encryption Specification (RAES).
RaesReadOnlyFile	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).

Enum Summary

Enum	Description
Type0RaesParameters.KeyStrength	Enumerates the AES cipher key strenghts.

Exception Summary

Exception	Description
RaesAuthenticationException	Thrown to indicate that a RAES file has been tampered with.
RaesException	Thrown if there is an issue when reading or writing a RAES file which is specific to the RAES file format.
RaesKeyException	Thrown to indicate that retrieving a key to encrypt or decrypt some pay load data in an RAES file has failed for some reason.
RaesParametersException	Thrown to indicate that no suitable cryptographic parameters have been provided or something is wrong with these parameters.

Package de.schlichtherle.truezip.crypto.raes Description

Reads and writes files according to the Random Access Encryption Specification (RAES). RAES is an extensible file format specification which enables fast, transparent random read access to encrypted arbitrary data (the pay load) with multistep authentication.

RAES is extensible, which means that the file header contains a single byte to identify the Type of the RAES file. Each data type specifies the cryptographic parameters required to decrypt or encrypt and authenticate the pay load data when reading or writing files of this type.

Currently, only Type-0 is specified, but more types may be added in future. Note that it is an error for an implementation to process an unknown type.

RAES features transparent random read access to the encrypted data. In order to do so, RAES has some invariants:

• RAES uses only block ciphers which are operated in Counter Mode (CTR). According to cryptanalysis by the US National Institute of Standards and Technology (NIST), CTR mode is considered to provide a strong level of privacy for the encrypted data.
• RAES provides two methods to authenticate the pay load:
  1. The first, mandatory method is the cipher Key and text Length Authentication Code (KLAC).
  2. The second, optional method is the well-known Message Authentication Code (MAC) on the full cipher text.

The mandatory KLAC method authenticates the cipher key and the length of the cipher text only. This is a very limited authentication which does not prevent an opponent to modify the contents of the cipher text. However, its processing time is constant (O(1)). Hence, relying on this authentication method alone may be acceptable if the pay load data provides another considerably secure means of authentication.

The optional MAC method authenticates the full cipher text. This is secure and should be used whenever the pay load does not to provide additional means of authentication. However, its processing time is linear to the size of the file (O(n)). Please note that this option does not require the cipher text to be decrypted first, which features comparably fast processing.

An example of a pay load which offers an authentication method by itself is the ZIP file format specification: Entries in a ZIP file are checksummed with CRC-32, which is applied to decompressed (deflated) source data. It is considered computationally infeasible to attack the integrity of a ZIP file which contains only compressed (deflated) entries and has a considerable size (say, at least 512KB) so that after decryption of the archive and decompression (inflation) the CRC-32 value of an entry still matches! This should hold true even though CRC-32 is not at all a good cryptographic hash function because of its frequent collisions, its linear output and small output size. It is the ZIP inflation algorithm which actually comes to its rescue!

RAES types

As said, RAES currently defines only Type-0 files. Type-0 has the following specifications:

• The encryption scheme is password based according to PKCS #5 V2.0 with the password base key derivation function (PBKDF) according to PKCS #12 V1.0. The latter allows to use Unicode password characters.
• The cipher algorithm is the Advanced Encryption Standard (AES) with a key length of 128, 192 or 256 bits.
• The salt is the same length as the cipher key length.
• The digest used to derive the cipher key, Initialization Vector (IV) and authentication codes is the Secure Hash Algorithm (SHA) Version 2 with 256 bits output length.

As usual with PKCS #12 the Initialization Vector (IV) for the CTR mode is derived from the password, the salt and the counter by the same Pseudo Random Number Generation (PRNG) function which is also used to derive the cipher key - so SHA-256.

Type 0 also supports the use of key files instead of passwords. If a key file is used for encryption, the first 512 bytes of the file are decoded into 16 bit Unicode characters in big endian format (without the byte order indicator) so that the byte order is preserved when the resulting character array is then again encoded into a byte array according to PKCS #12.

A file which shall be used as a key file for encryption must not be shorter than 512 bytes. However, in order to provide a certain level of fault tolerance for bogus RAES implementations, when using a key file for decryption an implementation is only required to assert that no more than the first 512 bytes of the key file are used. So the key file may actually be shorter.

As an optional step, an implementation should also check whether the key file used for encryption is a reasonably good source of entropy. The easiest way to achieve this is to use a compression API like Deflater. After compression, the result should be no shorter than the maximum key size (256 bits). Assuming a worst-case overhead for the deflater's algorithm of 100%, the minimum number of compressed bytes for the first 512 bytes of a key file should be no less than 2 * 256 / 8 = 64 bytes.