GoFiler Legato Script Reference   Legato v 1.5b Application v 5.24b

Table of Contents	< < Previous	Next >>

 

Chapter Five — General Functions (continued)

EncryptAsAES Function

Overview

The EncryptAsAES function encrypts a string or buffer using the AES (Advanced Encryption Standard) algorithm.

Syntax/Parameters

Syntax

int = EncryptAsAES ( 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 used as a string, the key size is determine 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 are not exactly 128, 192, 256 bits (16, 24 and 32 bytes respectively) will be zero padding to the appropriate number of bits. A key exceeding 256 bits will be truncated.

input

Input buffer of any type to 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. 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 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 AES_MODE_CBC will be used. 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 Remarks below.

size

An optional 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. Based on the input and mode the output can shrink or expand to a 16 byte boundary. The AES algorithm can return errors if current padding format is not allowed for the selected block chain mode.

Remarks

EncryptAsAES 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 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 to call the appropriate Encrypt or Decrypt function.

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 would be added to the data. This 1 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 you are doing your own padding. Otherwise data may be lost.

 

Related Functions

DecryptAsAES — Decrypts a buffer using AES.

Platform Support

Go13, Go16, GoFiler Complete, GoFiler Corporate, GoFiler, GoFiler Lite, GoXBRL

Legato IDE, Legato Basic

 

Table of Contents	< < Previous	Next >>

GoFiler Legato Script Reference — Generated on 10/21/2024

© 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.