RSA Security 5.2.2 manual Multiple Updates

Multiple Updates

Multiple Updates

An application can do multiple updates before the Final call. For example, suppose you have data from three different files that you want to encrypt into a single buffer. You could do this in three steps: read the contents of the first file into a buffer; read the next file, appending the contents to the end of the existing buffer; then append the contents of the third. But that would be clumsy if the contents of the three files are already in three buffers.

You do not have to put data together into a single buffer to encrypt it. Instead, call

B_EncryptUpdate with the first buffer, call it a second time with the second buffer, and one last time with the third buffer. Then call B_EncryptFinal once, after you have finished all Updates. Similarly, you can call B_DecryptUpdate more than once with blocks of encrypted data.

Multiple updates can also be useful for encrypting or decrypting large amounts of data. If you need to process a one-megabyte file, you could allocate a megabyte of memory, put the entire file into that memory buffer, and call Update once. But using such a large amount of memory is impractical or even impossible in some situations. An application is more robust if it allocates a smaller buffer — say, 64, 128 or 1024 bytes — transfers data from the file in increments, and processes each unit with a separate call to Update. Then it can call Final once for all Updates.

Crypto-C does not always encrypt or decrypt an entire block during an Update call. One reason it might not handle the whole block is because of padding. Padding is used with block ciphers to ensure the data satisfies input restrictions and may add bytes to the original data. See “Padding” on page 37 for more information. Padding and pad operations (encrypting or decrypting the padding, or stripping the pad) take place in Final, so Crypto-C may keep the last few bytes of any input to an Update call in a buffer. If there is another call to Update, then the bytes in that buffer were not the last bytes of input, and Crypto-C continues to encrypt or decrypt. If the next call is to Final, the bytes in the buffer are the last bytes of input, so Crypto-C adds the pad and encrypts it, or decrypts the final bytes and strips the pad.

Note: The output of a particular update may be larger than the input, because Crypto-C may be processing the current input plus some data in the buffer. Hence, an output buffer of an Update call should always be larger than the input length. For block ciphers, for example, the size of the output buffer may be as large as the length of the input plus the block size.

The following example demonstrates multiple updates. It corresponds to the file multencr.c; a similar example for decryption is in the file multdecr.c. Assume that the subroutine GetDataFromFile gets, at most, a specified number of bytes from a file,

C h a p t e r 2 Q u i c k S t a r t 2 9