de.schlichtherle.truezip.zip

Interface WinZipAesParameters

All Superinterfaces:

ZipCryptoParameters, ZipParameters

public interface WinZipAesParameters
extends ZipCryptoParameters

The parameters of this interface are used with WinZip AES encrypted entries.

Since:

TrueZIP 7.3

Author:

Christian Schlichtherle

See Also:

AES Encryption Information: Encryption Specification AE-1 and AE-2 (WinZip Computing, S.L.), AES Coding Tips for Developers (WinZip Computing, S.L.)

Method Summary

Modifier and Type	Method and Description
AesKeyStrength	getKeyStrength(String name) Returns the key strength to use for writing a WinZip AES entry.
byte[]	getReadPassword(String name, boolean invalid) Returns the password bytes to use for reading a WinZip AES entry.
byte[]	getWritePassword(String name) Returns the password bytes to use for writing a WinZip AES entry.
void	setKeyStrength(String name, AesKeyStrength keyStrength) Sets the key strength obtained from reading a WinZip AES entry.

Method Detail

getKeyStrength

AesKeyStrength getKeyStrength(String name)
                       throws ZipKeyException

Returns the key strength to use for writing a WinZip AES entry.

Parameters:

name - the ZIP entry name.

Returns:

The key strength to use for writing a WinZip AES entry.

Throws:

ZipKeyException - If key retrieval has failed for some reason.

getReadPassword

byte[] getReadPassword(String name,
                       boolean invalid)
                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!

Parameters:

name - the ZIP entry name.

invalid - true iff a previous call to this method returned an invalid password.

Returns:

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.

See Also:

getWritePassword(String)

getWritePassword

byte[] getWritePassword(String name)
                 throws ZipKeyException

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.

Parameters:

name - the ZIP entry name.

Returns:

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.

setKeyStrength

void setKeyStrength(String name,
                    AesKeyStrength keyStrength)
             throws ZipKeyException

Sets the key strength obtained from reading a WinZip AES entry.

Parameters:

name - the ZIP entry name.

keyStrength - the key strength obtained from reading a WinZip AES entry.

Throws:

ZipKeyException - If key retrieval has failed for some reason.