docs/aes_coding_tips.txt - third_party/libzip - Git at Google

 AES Coding Tips for Developers

 NOTE: WinZip^(R) users do not need to read or understand the information
 contained on this page. It is intended for developers of Zip file utilities.

 This document contains information that may be helpful to developers and other
 interested parties who wish to support the AE-1 and AE-2 AES encryption formats
 in their own Zip file utilities. WinZip Computing makes no warranties regarding
 the information provided in this document. In particular, WinZip Computing does
 not represent or warrant that the information provided here is free from errors
 or is suitable for any particular use, or that the file formats described here
 will be supported in future versions of WinZip. You should test and validate
 all code and techniques in accordance with good programming practice.

 This information supplements the basic encryption specification document found
 here.

 This document assumes that you are using Dr. Brian Gladman's AES encryption
 package. Dr. Gladman has generously made public a sample application that
 demonstrates the use of his encryption/decryption and other routines, and the
 code samples shown below are derived from this sample application. Dr.
 Gladman's AES library and the sample application are available from the AES
 project page on Dr. Gladman's web site.

 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

 Generating a salt value

 Please read the discussion of salt values in the encryption specification.

 Dr. Gladman has provided a pseudo-random number generator in the files PRNG.C
 and PRNG.H. You may find this suitable for generating salt values. These files
 are included in the sample package available through the AES project page on
 Dr. Gladman's web site.

 Here are guidelines for using Dr. Gladman's generator. Note that the generator
 is used rather like an I/O stream: it is opened (initialized), used, and
 finally closed. To obtain the best results, it is recommended that you
 initialize the generator when your application starts and close it when your
 application closes. (If you are coding in C++, you may wish to wrap these
 actions in a C++ class that initializes the generator on construction and
 closes it on destruction.)

  1. You will need to provide an entropy function in your code for
     initialization of the generator. The entropy function need not be
     particularly sophisticated for this use. Here is one possibility for such a
     function, based primarily upon the Windows performance counter:

     int entropy_fun(
      unsigned char buf[],
      unsigned int len)
         {
         unsigned __int64 pentium_tsc[1];
         unsigned int     i;
         static unsigned int num = 0;
         // this sample code returns the following sequence of entropy information
         // - the current 8-byte Windows performance counter value
         // - an 8-byte representation of the current date/time
         // - an 8-byte value built from the current process ID and thread ID
         // - all subsequent calls return the then-current 8-byte performance
         //      counter value
         switch (num)
             {
         case 1:
             ++num;
             // use a value that is unlikely to repeat across system reboots
             GetSystemTimeAsFileTime((FILETIME *)pentium_tsc);
             break;
         case 2:
             ++num;
             {
             // use a value that distinguishes between different instances of this
             // code that might be running on different processors at the same time
             unsigned __int32 processtest = GetCurrentProcessId();
             unsigned __int32 threadtest = GetCurrentThreadId();
             pentium_tsc[0] = processtest;
             pentium_tsc[0] = (pentium_tsc[0] << 32) + threadtest;
             }
             break;
         case 0:
             ++num;
             // fall through to default case
         default:
             // use a rapidly-changing value
             //  Note: check QueryPerformanceFrequency() first to
             //  ensure that QueryPerformanceCounter() will work.
             QueryPerformanceCounter((LARGE_INTEGER *)pentium_tsc);
             break;
             }
         for(i = 0; i < 8 && i < len; ++i)
             buf[i] = ((unsigned char*)pentium_tsc)[i];
         return i;
         }

     Note: the required prototype for the entropy function is defined in PRNG.H.

  2. Initialize the generator by calling prng_init(), providing the addresses of
     your entropy function and of an instance of a prng_ctx structure (defined
     in PRNG.H). The prng_ctx variable maintains a context for the generator and
     is used as a parameter for the other generator functions. Therefore, the
     variable's state must be maintained until the generator is closed.

     prng_ctx ctx;
     prng_init(entropy_fun, &ctx);

     You only need to do this once per application session (as long as you keep
     the "stream" open).

  3. To obtain a sequence of random bytes of arbitrary size, use prng_rand().
     This code obtains 16 random bytes, suitable for use as a salt value for
     256-bit AES encryption:

     unsigned char buffer[16];
     prng_rand(buffer, sizeof(buffer), &ctx);

     Note that the ctx parameter is the same prng_ctx variable that was used in
     the initialization call.

  4. When you are done with the generator (this would normally be when your
     application closes), close it by calling prng_end:

     prng_end(&ctx);

     Again, the ctx parameter is the same prng_ctx variable that was used in the
     initialization call.

 Encryption and decryption

 The actual encryption and decryption of data are handled quite similarly, and
 again are rather stream-like: a stream is "opened", data is passed to it for
 encryption or decryption, and then it is closed. The password verifier is
 returned when the stream is opened, and the authentication code is returned
 when the stream is closed.

 Here is the basic technique:

  1. Initialize the "stream" for encryption or decryption and obtain the
     password verification value.

     There is no difference in the initialization, regardless of whether you are
     encrypting or decrypting:

     fcrypt_ctx zctx;     // the encryption context
     int rc = fcrypt_init(
       KeySize,       // extra data value indicating key size
       pszPassword,     // the password
       strlen(pszPassword), // number of bytes in password
       achSALT,       // the salt
       achPswdVerifier,   // on return contains password verifier
       &zctx);       // encryption context

     The return value is 0 if the initialization was successful; non-zero values
     indicate errors. Note that passwords are null-terminated ANSI strings;
     embedded nulls must not be used. (To avoid incompatibilities between the
     various character sets in use, especially in different versions of Windows,
     users should be encouraged to use passwords containing only the "standard"
     characters in the range 32-127.)

     The function returns the password verification value in achPswdVerifier,
     which must be a 2-byte buffer. If you are encrypting, store this value in
     the Zip file as indicated by the encryption specification. If you are
     decrypting, compare this returned value to the value stored in the Zip
     file. If they are different, then either the password provided by your user
     was incorrect or the encrypted file has been altered in some way since it
     was encrypted. (Note that if they match, there is still a 1 in 65,536
     chance that an incorrect password was provided.)

     The initialized encryption context (zctx) is used as a parameter to the
     encryption/decryption functions. Therefore, its state must be maintained
     until the "stream" is closed.

  2. Encrypt or decrypt the data.

     To encrypt:

     fcrypt_encrypt(
       pchData, // pointer to the data to encrypt
       cb,   // how many bytes to encrypt
       &zctx); // encryption context

     To decrypt:

     fcrypt_decrypt(
       pchData, // pointer to the data to decrypt
       cb,   // how many bytes to decrypt
       &zctx); // decryption context

     You may need to call the encrypt or decrypt function multiple times,
     passing in successive chunks of data in the buffer. For AE-1 and AE-2
     compatibility, the buffer size must be a multiple of 16 bytes except for
     the last buffer, which may be smaller. For efficiency, a larger buffer size
     such as 32,768 would generally be used.

     Note: to encrypt zero-length files, simply skip this step. You will still
     obtain and use the password verifier (step 1) and authentication code (step
     3).

  3. Close the "stream" and obtain the authentication code.

     When encryption/decryption is complete, close the "stream" as follows:

     int rc = fcrypt_end(
       achMAC, // on return contains the authentication code
       &zctx); // encryption context

     The return value is the size of the authentication code, which will always
     be 10 for AE-1 and AE-2. The authentication code itself is returned in your
     buffer at achMAC, which is an array of char, sized to hold at least 10
     characters. If you are encrypting, store this value in the Zip file as
     indicated by the encryption specification; if you are decrypting, compare
     this value to the value stored in the Zip file. If the values are
     different, either the password is incorrect or the encrypted data has been
     altered subsequent to storage.

     Note that decryption can fail even if the encrypted data is unaltered and
     the password verifier was correct in step 1. The password verifier is
     useful as a quick way to detect most incorrect passwords, but it is not
     perfect and on rare occasions (1 out of 65,536) it will fail to detect an
     incorrect password. It is therefore important for you to check the
     authentication code on completion even though the password verifier was
     correct.

 Notes

   • Dr. Gladman's AES code depends on the byte order (little-endian or
     big-endian) used by the computing platform the code will run on. This is
     determined by a C preprocessor constant called PLATFORM_BYTE_ORDER, which
     is defined in the file AESOPT.H. You should be sure that
     PLATFORM_BYTE_ORDER gets the proper value for your platform; if it does
     not, you will need to define it yourself to the correct value. When using
     the Microsoft compiler on Intel platforms it does get the proper value,
     which on these platforms is AES_LITTLE_ENDIAN. We have, however, had a
     report that it does not default properly when Borland C++ Builder is used,
     and that manual assignment is necessary. For additional information on this
     topic, refer to the comments within AESOPT.H.

 Change history

 Changes made in document version 1.04, July, 2008:

  A. Sample Entropy Function

     The sample entropy function was changed to include information near the
     very beginning of the entropy stream that's unique to the day and to the
     process and thread.

 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

 Document version: 1.04
 Last modified: July 21, 2008

 Copyright(C) 2003-2016 WinZip International LLC.
 All Rights Reserved
	AES Coding Tips for Developers

	NOTE: WinZip^(R) users do not need to read or understand the information
	contained on this page. It is intended for developers of Zip file utilities.

	This document contains information that may be helpful to developers and other
	interested parties who wish to support the AE-1 and AE-2 AES encryption formats
	in their own Zip file utilities. WinZip Computing makes no warranties regarding
	the information provided in this document. In particular, WinZip Computing does
	not represent or warrant that the information provided here is free from errors
	or is suitable for any particular use, or that the file formats described here
	will be supported in future versions of WinZip. You should test and validate
	all code and techniques in accordance with good programming practice.

	This information supplements the basic encryption specification document found
	here.

	This document assumes that you are using Dr. Brian Gladman's AES encryption
	package. Dr. Gladman has generously made public a sample application that
	demonstrates the use of his encryption/decryption and other routines, and the
	code samples shown below are derived from this sample application. Dr.
	Gladman's AES library and the sample application are available from the AES
	project page on Dr. Gladman's web site.

	━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

	Generating a salt value

	Please read the discussion of salt values in the encryption specification.

	Dr. Gladman has provided a pseudo-random number generator in the files PRNG.C
	and PRNG.H. You may find this suitable for generating salt values. These files
	are included in the sample package available through the AES project page on
	Dr. Gladman's web site.

	Here are guidelines for using Dr. Gladman's generator. Note that the generator
	is used rather like an I/O stream: it is opened (initialized), used, and
	finally closed. To obtain the best results, it is recommended that you
	initialize the generator when your application starts and close it when your
	application closes. (If you are coding in C++, you may wish to wrap these
	actions in a C++ class that initializes the generator on construction and
	closes it on destruction.)

	1. You will need to provide an entropy function in your code for
	initialization of the generator. The entropy function need not be
	particularly sophisticated for this use. Here is one possibility for such a
	function, based primarily upon the Windows performance counter:

	int entropy_fun(
	unsigned char buf[],
	unsigned int len)
	{
	unsigned __int64 pentium_tsc[1];
	unsigned int i;
	static unsigned int num = 0;
	// this sample code returns the following sequence of entropy information
	// - the current 8-byte Windows performance counter value
	// - an 8-byte representation of the current date/time
	// - an 8-byte value built from the current process ID and thread ID
	// - all subsequent calls return the then-current 8-byte performance
	// counter value
	switch (num)
	{
	case 1:
	++num;
	// use a value that is unlikely to repeat across system reboots
	GetSystemTimeAsFileTime((FILETIME *)pentium_tsc);
	break;
	case 2:
	++num;
	{
	// use a value that distinguishes between different instances of this
	// code that might be running on different processors at the same time
	unsigned __int32 processtest = GetCurrentProcessId();
	unsigned __int32 threadtest = GetCurrentThreadId();
	pentium_tsc[0] = processtest;
	pentium_tsc[0] = (pentium_tsc[0] << 32) + threadtest;
	}
	break;
	case 0:
	++num;
	// fall through to default case
	default:
	// use a rapidly-changing value
	// Note: check QueryPerformanceFrequency() first to
	// ensure that QueryPerformanceCounter() will work.
	QueryPerformanceCounter((LARGE_INTEGER *)pentium_tsc);
	break;
	}
	for(i = 0; i < 8 && i < len; ++i)
	buf[i] = ((unsigned char*)pentium_tsc)[i];
	return i;
	}

	Note: the required prototype for the entropy function is defined in PRNG.H.

	2. Initialize the generator by calling prng_init(), providing the addresses of
	your entropy function and of an instance of a prng_ctx structure (defined
	in PRNG.H). The prng_ctx variable maintains a context for the generator and
	is used as a parameter for the other generator functions. Therefore, the
	variable's state must be maintained until the generator is closed.

	prng_ctx ctx;
	prng_init(entropy_fun, &ctx);

	You only need to do this once per application session (as long as you keep
	the "stream" open).

	3. To obtain a sequence of random bytes of arbitrary size, use prng_rand().
	This code obtains 16 random bytes, suitable for use as a salt value for
	256-bit AES encryption:

	unsigned char buffer[16];
	prng_rand(buffer, sizeof(buffer), &ctx);

	Note that the ctx parameter is the same prng_ctx variable that was used in
	the initialization call.

	4. When you are done with the generator (this would normally be when your
	application closes), close it by calling prng_end:

	prng_end(&ctx);

	Again, the ctx parameter is the same prng_ctx variable that was used in the
	initialization call.

	Encryption and decryption

	The actual encryption and decryption of data are handled quite similarly, and
	again are rather stream-like: a stream is "opened", data is passed to it for
	encryption or decryption, and then it is closed. The password verifier is
	returned when the stream is opened, and the authentication code is returned
	when the stream is closed.

	Here is the basic technique:

	1. Initialize the "stream" for encryption or decryption and obtain the
	password verification value.

	There is no difference in the initialization, regardless of whether you are
	encrypting or decrypting:

	fcrypt_ctx zctx; // the encryption context
	int rc = fcrypt_init(
	KeySize, // extra data value indicating key size
	pszPassword, // the password
	strlen(pszPassword), // number of bytes in password
	achSALT, // the salt
	achPswdVerifier, // on return contains password verifier
	&zctx); // encryption context

	The return value is 0 if the initialization was successful; non-zero values
	indicate errors. Note that passwords are null-terminated ANSI strings;
	embedded nulls must not be used. (To avoid incompatibilities between the
	various character sets in use, especially in different versions of Windows,
	users should be encouraged to use passwords containing only the "standard"
	characters in the range 32-127.)

	The function returns the password verification value in achPswdVerifier,
	which must be a 2-byte buffer. If you are encrypting, store this value in
	the Zip file as indicated by the encryption specification. If you are
	decrypting, compare this returned value to the value stored in the Zip
	file. If they are different, then either the password provided by your user
	was incorrect or the encrypted file has been altered in some way since it
	was encrypted. (Note that if they match, there is still a 1 in 65,536
	chance that an incorrect password was provided.)

	The initialized encryption context (zctx) is used as a parameter to the
	encryption/decryption functions. Therefore, its state must be maintained
	until the "stream" is closed.

	2. Encrypt or decrypt the data.

	To encrypt:

	fcrypt_encrypt(
	pchData, // pointer to the data to encrypt
	cb, // how many bytes to encrypt
	&zctx); // encryption context

	To decrypt:

	fcrypt_decrypt(
	pchData, // pointer to the data to decrypt
	cb, // how many bytes to decrypt
	&zctx); // decryption context

	You may need to call the encrypt or decrypt function multiple times,
	passing in successive chunks of data in the buffer. For AE-1 and AE-2
	compatibility, the buffer size must be a multiple of 16 bytes except for
	the last buffer, which may be smaller. For efficiency, a larger buffer size
	such as 32,768 would generally be used.

	Note: to encrypt zero-length files, simply skip this step. You will still
	obtain and use the password verifier (step 1) and authentication code (step
	3).

	3. Close the "stream" and obtain the authentication code.

	When encryption/decryption is complete, close the "stream" as follows:

	int rc = fcrypt_end(
	achMAC, // on return contains the authentication code
	&zctx); // encryption context

	The return value is the size of the authentication code, which will always
	be 10 for AE-1 and AE-2. The authentication code itself is returned in your
	buffer at achMAC, which is an array of char, sized to hold at least 10
	characters. If you are encrypting, store this value in the Zip file as
	indicated by the encryption specification; if you are decrypting, compare
	this value to the value stored in the Zip file. If the values are
	different, either the password is incorrect or the encrypted data has been
	altered subsequent to storage.

	Note that decryption can fail even if the encrypted data is unaltered and
	the password verifier was correct in step 1. The password verifier is
	useful as a quick way to detect most incorrect passwords, but it is not
	perfect and on rare occasions (1 out of 65,536) it will fail to detect an
	incorrect password. It is therefore important for you to check the
	authentication code on completion even though the password verifier was
	correct.

	Notes

	• Dr. Gladman's AES code depends on the byte order (little-endian or
	big-endian) used by the computing platform the code will run on. This is
	determined by a C preprocessor constant called PLATFORM_BYTE_ORDER, which
	is defined in the file AESOPT.H. You should be sure that
	PLATFORM_BYTE_ORDER gets the proper value for your platform; if it does
	not, you will need to define it yourself to the correct value. When using
	the Microsoft compiler on Intel platforms it does get the proper value,
	which on these platforms is AES_LITTLE_ENDIAN. We have, however, had a
	report that it does not default properly when Borland C++ Builder is used,
	and that manual assignment is necessary. For additional information on this
	topic, refer to the comments within AESOPT.H.

	Change history

	Changes made in document version 1.04, July, 2008:

	A. Sample Entropy Function

	The sample entropy function was changed to include information near the
	very beginning of the entropy stream that's unique to the day and to the
	process and thread.

	━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

	Document version: 1.04
	Last modified: July 21, 2008

	Copyright(C) 2003-2016 WinZip International LLC.
	All Rights Reserved