de.schlichtherle.truezip.zip.WinZipAesParameters Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of truezip-driver-zip Show documentation
The file system driver family for ZIP and related archive file types. Add the JAR artifact of this module to the run time class path to make its file system drivers available for service location in the client API modules.
There is a newer version: 7.7.10
Show newest version
/*
 * Copyright (C) 2005-2013 Schlichtherle IT Services.
 * All rights reserved. Use is subject to license terms.
 */
package de.schlichtherle.truezip.zip;

import de.schlichtherle.truezip.crypto.param.AesKeyStrength;

/**
 * The parameters of this interface are used with WinZip AES encrypted entries.
 *
 * @since   TrueZIP 7.3
 * @see     AES Encryption Information: Encryption Specification AE-1 and AE-2 (WinZip Computing, S.L.)
 * @see     AES Coding Tips for Developers (WinZip Computing, S.L.)
 * @author  Christian Schlichtherle
 */
public interface WinZipAesParameters extends ZipCryptoParameters {

    /**
     * Returns the password bytes to use for writing a WinZip AES entry.
     * 
     * WARNING: Unfortunately, the document
     * AES Encryption Information: Encryption Specification AE-1 and AE-2
     * does not specify how password strings should get encoded to bytes.
     * This means that whatever encoding you chose in the implementation,
     * chances are that an authorized third party will not be able to read
     * WinZip AES entries you have written.
     * This could even be your future self when you are using another
     * application or platform then!
     * 

     * There are several reasonable schemes you could chose to encode password
     * characters to bytes:
     * 

     * You could follow the recommendation in the document
     *     AES Coding Tips for Developers
     *     and limit the character set to the non-control characters of
     *     US-ASCII.
     *     However, this severely limits the password search space for brute
     *     force attacks.
     * 
You could use the same character set which is used to encode entry
     *     names and comments in the ZIP file, e.g. UTF-8 or CP437.
     *     This should be the preferred choice, but would not conform
     *     to WinZip's recommendation.
     *     In the case of encodings other than UTF-8, this would still limit
     *     the password search space, but not as much as US-ASCII.
     * 
If you are not concerned about interoperability with authorized
     *     third parties, including yourself when using another application or
     *     platform, then you could simply use UTF-8.
     *     This would provide the largest password search space and follow the
     *     convention for JAR files, but again, this would not conform to
     *     WinZip's recommendation.
     * 
     * 
     * A reasonable alternative implementation could encode the given char
     * array using the same character set which is used to encode entry names
     * and comments, e.g. UTF-8 or CP437.
     *
     * @param  name the ZIP entry name.
     * @return A clone of the byte array holding the password to use
     *         for writing a WinZip AES entry.
     * @throws ZipKeyException If key retrieval has failed for some reason.
     */
    byte[] getWritePassword(String name)
    throws ZipKeyException;

    /**
     * Returns the password bytes to use for reading a WinZip AES entry.
     * This method is called consecutively until either the returned password
     * bytes are successfully validated or an exception is thrown.
     * 
     * WARNING: Unfortunately, the document
     * AES Encryption Information: Encryption Specification AE-1 and AE-2
     * does not specify how password strings should get encoded to bytes.
     * This means that whatever encoding you chose in the implementation,
     * chances are that you will not be able to read WinZip AES entries a third
     * party has written.
     * This could even be your past self when you were using another
     * application or platform at the time!
     *
     * @see    #getWritePassword(String)
     * @param  name the ZIP entry name.
     * @param  invalid {@code true} iff a previous call to this method returned
     *         an invalid password.
     * @return A clone of the byte array holding the password to use
     *         for reading a WinZip AES entry.
     * @throws ZipKeyException If key retrieval has failed for some reason.
     */
    byte[] getReadPassword(String name, boolean invalid)
    throws ZipKeyException;

    /**
     * Returns the key strength to use for writing a WinZip AES entry.
     *
     * @param  name the ZIP entry name.
     * @return The key strength to use for writing a WinZip AES entry.
     * @throws ZipKeyException If key retrieval has failed for some reason.
     */
    AesKeyStrength getKeyStrength(String name)
    throws ZipKeyException;

    /**
     * Sets the key strength obtained from reading a WinZip AES entry.
     *
     * @param  name the ZIP entry name.
     * @param  keyStrength the key strength obtained from reading a WinZip AES
     *         entry.
     * @throws ZipKeyException If key retrieval has failed for some reason.
     */
    void setKeyStrength(String name, AesKeyStrength keyStrength)
    throws ZipKeyException;
}