  |
GoFiler Legato Script Reference
Legato v 1.5d Application v 5.25a
|
| Table of Contents | < < Previous | Next >> |
Chapter Five — General Functions (continued)
Overview
The DecryptAsAES function decrypts a buffer using the AES (Advanced Encryption Standard) algorithm.
Syntax/Parameters
Syntax
int = DecryptAsAES ( parameter key, parameter input, parameter *output, [int mode],
[parameter vector], [int
size], [int padding] );
Parameters
key
A string or char array to use as the encryption key. If supplied as a string, the key size is determined by the first zero-terminating byte. For a character array, the size of the character array is used as the key size. A key that is not exactly 128, 192, 256 bits (16, 24 and 32 bytes respectively) will be zero padded to the appropriate number of bits. A key exceeding 256 bits will be truncated.
input
Input buffer of any type to decrypt except it must be in contiguous storage. See Section 3.7 Contiguous Data for more information. The parameter is treated as a pointer to the area of memory where the variable is held. Strings are an exception in that they must be zero-terminated (see Remarks below).
output
A variable name to contain the decrypted data. It cannot be a literal or a calculated expression value. It can be of any type except it must be in contiguous storage. See Section 3.7 Contiguous Data for more information. The parameter is treated as a pointer to the area of memory where the variable is held. Strings are an exception in that they must be zero-terminated (see Remarks below).
The output buffer must be must be the same size or larger than the input buffer and should accommodate up to 16 additional bytes for padding. The resulting value will be in binary form.
mode
An int specifying one of three block chaining modes: AES_MODE_ECB (1), AES_MODE_CBC (2) and AES_MODE_CFB1 (3). If not specified, the default value is AES_MODE_CBC. See Remarks below.
vector
An optional 16 byte buffer containing an initialization vector for the block chain method. The vector must be the same between encryption and decryption. If not specified, a 16 byte buffer of zeros will be used. See the Remarks section.
size
An optional int containing a size specification. If specified, it must be the same or smaller than both the input and output buffers.
padding
An optional int specifying the padding mode for the input data. If must be one of the following: AES_PAD_ZEROFILL (0), AES_PAD_RFC2040 (1) or AES_PAD_NOPADDING (2). The default is AES_PAD_ZEROFILL.
Return Value
Returns an int as the size of the encrypted buffer in bytes on success or a formatted error code on failure. Based on the input and mode the output can shrink or expand to a 16 byte boundary. The AES algorithm can return errors if certain parameters conflict or the incoming data is in error.
Remarks
DecryptAsAES is one of the few functions that will alter the contents of a source parameter. The output variable will be written as the result.
The AES (Advanced Encryption Standard) is based on the Rijndael cipher, which, in turn, is based on a design principle known as a substitution-permutation network. This makes the algorithm very fast, but, unlike its predecessor DES, it supports key sizes of 128, 192, or 256 bits. The encryption is symmetrical but due to the various padding and block chaining modes it is recommended that the appropriate encrypt or decrypt function is called.
Block chaining modes are provided to ensure confidentiality. The basic block chain mode is known as ECB, or Electronic Codebook (AES_MODE_ECB). This method divides the incoming data into blocks and then encrypts each block separately. This method is not recommended for actual encryption as patterns in the source data will still be present in the encrypted data. The CBC or Cipher Block Chaining (AES_MODE_CBC) method XORs the result of the previous encrypted block with the current plaintext before it is encrypted. An initialization vector is used when XORing the first block. This block chain causes the resulting encrypted data to appear random. The CFB or Cipher Feedback (AES_MODE_CFB1) method encrypts the result of the last block and then XORs that with the plaintext shifting the data 1 bit each time. This method is very similar to CBC but can be done on variable lengths of bits. Through Legato only byte boundaries can be encrypted so this block chain method will automatically use AES_PAD_ZEROFILL even if it is not specified.
The different padding modes are as follows:
| Define | Value | Description | |||
| AES_PAD_ZEROFILL | 0 | Incoming data is zero filled to reach a block boundary. For example, if 15 bytes of data were encrypted, an extra 0 would be added to the data before the encryption. This method is good for string data as the extra zeroes will be ignored. The output buffer must be at least 16 bytes larger than the incoming data. | |||
| AES_PAD_RFC2040 | 1 | Incoming data is filled with bytes that indicate the size of the padding. Data is always padded even if the data ends on a block boundary. For example, if 15 bytes of data were encrypted, an extra 1 byte would be added to the data. This 1 byte would then be removed when decrypting the data. The output buffer must be at least 16 bytes larger than the incoming data. | |||
| AES_PAD_NOPADDING | 2 | Incoming data is truncated to the last full block. This method should only be used if the programmer is handling the padding. Otherwise data may be lost. |
Related Functions
Platform Support
Go13, Go16, GoFiler Complete, GoFiler Corporate, GoFiler, GoFiler Lite, GoXBRL
Legato IDE, Legato Basic
| Table of Contents | < < Previous | Next >> |
© 2012-2024 Novaworks, LLC. All rights reserved worldwide. Unauthorized use, duplication or transmission prohibited by law. Portions of the software are protected by US Patents 10,095,672, 10,706,221 and 11,210,456. GoFiler™ and Legato™ are trademarks of Novaworks, LLC. EDGAR® is a federally registered trademark of the U.S. Securities and Exchange Commission. Novaworks is not affiliated with or approved by the U.S. Securities and Exchange Commission. All other trademarks are property of their respective owners. Use of the features specified in this language are subject to terms, conditions and limitations of the Software License Agreement.