[openssl.org #1638] OpenSSL doc on EVP_*Final() inaccurate; should mention EVP_CIPHER_CTX_cleanup()

[West, Larry via RT]

Currently the manual page
http://www.openssl.org/docs/crypto/EVP_EncryptInit.html paragraph for
EVP_DecryptFinal() says:

        EVP_EncryptFinal(), EVP_DecryptFinal() and EVP_CipherFinal()
behave in a similar way to EVP_EncryptFinal_ex(), EVP_DecryptFinal_ex()
and EVP_CipherFinal_ex() except ctx is automatically cleaned up after
the call.

In the paragraphs for those three *_ex() functions, there's nothing
explicit about cleanup, though right afterwards there is a seemingly
unrelated paragraph:

        EVP_CIPHER_CTX_cleanup() clears all information from a cipher
context and free up any allocated memory associate with it. It should be
called after all operations using a cipher are complete so sensitive
information does not remain in memory.

It wasn't until Rational Purify pointed me at a recurring 244-byte
memory leak:

        MLK: 244 bytes leaked at 0x40130c10
          * This memory was allocated from:
          malloc         [rtlib.o]
          default_malloc_ex [libcrypto.sl.0.9.8]
          CRYPTO_malloc  [libcrypto.sl.0.9.8]
          EVP_CipherInit_ex [libcrypto.sl.0.9.8]
          EVP_DecryptInit [libcrypto.sl.0.9.8]

...that I realized there was a problem.   Reading the code and then
googling led me to the Changelog paragraph section from Dec 2002:

          *) Remove most calls to EVP_CIPHER_CTX_cleanup() in evp_enc.c,
this 
             allows existing EVP_CIPHER_CTX structures to be reused
after
             calling EVP_*Final(). This behaviour is used by encryption
             BIOs and some applications. This has the side effect that
             applications must explicitly clean up cipher contexts with
             EVP_CIPHER_CTX_cleanup() or they will leak memory.
             [Steve Henson]

I think that, as documentation goes, this is sufficiently obscure that
it merits a change to the man page section.   Based on the 0.9.8a
source, here's what I would suggest as an improved form of that first
paragraph I quoted:

        EVP_EncryptFinal(), EVP_DecryptFinal() and EVP_CipherFinal() are
identical to EVP_EncryptFinal_ex(), EVP_DecryptFinal_ex() and
EVP_CipherFinal_ex() and as with those functions,
EVP_CIPHER_CTX_cleanup() should be called after each call to release
memory allocated in the EVP_CIPHER_CTX structure.   Note that this is no
longer automatically done, so as to allow that structure to be reused
for a performance gain, behavior which is used by encryption BIOs and
some applications.

Many thanks in advance,
 
Larry West
Intuit San Diego
858-215-9552
 
 

Currently the manual page http://www.openssl.org/docs/crypto/EVP_EncryptInit.html paragraph for EVP_DecryptFinal() says:

EVP_EncryptFinal(), EVP_DecryptFinal() and EVP_CipherFinal() behave in a similar way to EVP_EncryptFinal_ex(), EVP_DecryptFinal_ex() and EVP_CipherFinal_ex() except ctx is automatically cleaned up after the call.

In the paragraphs for those three *_ex() functions, there's nothing explicit about cleanup, though right afterwards there is a seemingly unrelated paragraph:

EVP_CIPHER_CTX_cleanup() clears all information from a cipher context and free up any allocated memory associate with it. It should be called after all operations using a cipher are complete so sensitive information does not remain in memory.

It wasn't until Rational Purify pointed me at a recurring 244-byte memory leak:

MLK: 244 bytes leaked at 0x40130c10
  * This memory was allocated from:
  malloc         [rtlib.o]
  default_malloc_ex [libcrypto.sl.0.9.8]
  CRYPTO_malloc  [libcrypto.sl.0.9.8]
  EVP_CipherInit_ex [libcrypto.sl.0.9.8]
  EVP_DecryptInit [libcrypto.sl.0.9.8]

...that I realized there was a problem.   Reading the code and then googling led me to the Changelog paragraph section from Dec 2002:

  *) Remove most calls to EVP_CIPHER_CTX_cleanup() in evp_enc.c, this
     allows existing EVP_CIPHER_CTX structures to be reused after
     calling EVP_*Final(). This behaviour is used by encryption
     BIOs and some applications. This has the side effect that
     applications must explicitly clean up cipher contexts with
     EVP_CIPHER_CTX_cleanup() or they will leak memory.
     [Steve Henson]

I think that, as documentation goes, this is sufficiently obscure that it merits a change to the man page section.   Based on the 0.9.8a source, here's what I would suggest as an improved form of that first paragraph I quoted:

EVP_EncryptFinal(), EVP_DecryptFinal() and EVP_CipherFinal() are identical to EVP_EncryptFinal_ex(), EVP_DecryptFinal_ex() and EVP_CipherFinal_ex() and as with those functions, EVP_CIPHER_CTX_cleanup() should be called after each call to release memory allocated in the EVP_CIPHER_CTX structure.   Note that this is no longer automatically done, so as to allow that structure to be reused for a performance gain, behavior which is used by encryption BIOs and some applications.

Many thanks in advance,

 

Larry West

Intuit San Diego

858-215-9552