docs/aes_coding_tips.txt

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