de.schlichtherle.truezip.crypto.raes.package-info Maven / Gradle / Ivy
/*
* Copyright (C) 2005-2015 Schlichtherle IT Services.
* All rights reserved. Use is subject to license terms.
*/
/**
* 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:
*
* - The first, mandatory method is the cipher Key and text Length
* Authentication Code (KLAC).
*
- 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
* {@link java.util.zip.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.
*/
@edu.umd.cs.findbugs.annotations.DefaultAnnotation(edu.umd.cs.findbugs.annotations.NonNull.class)
package de.schlichtherle.truezip.crypto.raes;