ENCRYPT

ADELIA	VADELIA	SADELIA	WADELIA	EADELIA
(I/B)	(I/B) (C/S)	(B) (S)	(I/B) (C/S)	(B) (C/S)

User paragraph

All

Syntax

ENCRYPT Algorithm Key InitVect Data Result

Algorithm	→		'AlphaConstant' \| AlphaVar
Key	→		*KEY (AlphaConstant \| AlphaVar)
InitVect	→		*INIT_VECT (AlphaConstant \| AlphaVar) \| Nothing
Data	→		AlphaConstant Normalize \| AlphaVar Normalize \| ImageVar
Normalize		→	*NORMALIZE \| Nothing
Result	→		AlphaVar Encoding \| ImageVar
Encoding		→	HEXA \| BASE64 \| Nothing

Description

This instruction is used to encrypt the input string using the specified key and algorithm.

The encryption algorithms available depend on the platform and possibly additional components installed. DES, Triple DES (DESede), AES, RC2, RC4 and RSA algorithms are available on all the platforms.

The content of the algorithm variable follows the Java naming standard, i.e. it takes the ALGORITHM[/BLOCKMODE/PADDING] form, where:

- ALGORITHM refers to the encryption algorithm used (AES, DES).
- BLOCKMODE (optional) refers to the block processing mode.
  ECB mode is used by default. This parameter is not provided for the RSA algorithm.
- PADDING refers to the padding mode used.
  In the block encryption algorithm (excluding RSA), the encryption algorithm can only process a whole number of blocks (the size of which depends on the algorithm used).
  If the length of the data to encrypt does not correspond to a number of blocks, the padding algorithm is used to complete the block data.
  If the "NoPadding"; value is specified, the length of data to encrypt must correspond to a whole number of blocks.
  
  For the padding definition, Adelia accepts a special ";ZeroPadding"; value which is not a standard padding.
  This value is equivalent to the ";NoPadding"; specification, completing the data with zeros, if necessary, in the case of block encryption algorithms.
  This gives a more compact result.

With the exception of the RSA algorithm, the key (*KEY parameter) must be provided encoded in hexadecimal (the string length is therefore equal to twice the length of the key).
The key must have a length compatible with the encryption algorithm used.

The RSA algorithm is an asymmetric algorithm using two keys (one public and one private). These keys must be provided in PEM format.

When encryption is performed using one of these keys, decryption can only be performed with the other key.

Encryption is normally performed using the public key and decryption with the private key, but the opposite is possible as this mode is generally used to generate a signature.

Caution: when using a private key, the key must be encoded in PKCS #8 format (the key must contain a -----BEGIN PRIVATE KEY----- rather than -----BEGIN RSA PRIVATE KEY----- declaration).

The Windows (OpenSSL) version and certain Java encryption providers (Bouncy Castle) also accept keys encoded in PKCS#1 format (-----BEGIN RSA PRIVATE KEY-----).

The initialization vector (*INIT_VECT parameter) is an optional item of data used to add a random part to the encryption mechanism. If it is provided, it must be given again identically in the decryption phase.

The initialization vector must be provided encoded in hexadecimal. Its length corresponds to the length of a data block in the chosen encryption algorithm - for example 8 bytes (16 encoded characters) for the DES algorithm or 16 bytes (32 encoded characters) for the AES algorithm.

If the length of the initialization vector does not correspond to the required size, it will either be truncated or completed with zeros. If the chosen algorithm does not require an initialization vector, the parameter will be ignored.

The *NORMALIZE parameter is used to trigger the conversion of the input string into UTF-8 format. This provides a result which is independent from the code page used and so from the execution platform. This parameter is only available for input ALPHA variables as the IMAGE type are read as binary data.

The encoding parameter specifies if the result needs to be encoded in hexadecimal (*HEXA) or base 64 (*BASE64). If nothing is specified, encoding will be in hexadecimal. This parameter is only available for output ALPHA variables. For output IMAGE variables, the result is stored directly as binary data.

The *RETURN_CODE reserved word can be tested to check if the operation has been performed successfully.

If an error is encountered, this reserved word returns a value different from *NORMAL and the *RETURN_MSG reserved word provides a description of the error.

The possible values for *RETURN_CODE are the following:

0	The operation was successful.
1	Encryption engine internal error. In this case, the message specifies the actual error and depends on the platform.
2	Invalid algorithm.
3	Invalid key (length or key format in the case of an RSA algorithm).
4	Invalid initialization vector. This error is only returned in the case of a block encryption algorithm accepting an initialization vector. In this case, the length of the initialization vector must correspond to the encryption algorithm block size. In other cases, the initialization vector is ignored.
6	Invalid output field. The output variable is too small to contain the encrypted data.

Considerations relating to the size of the output variable.

The Adelia output variable must be big enough to contain the encrypted and encoded data or an error will be issued.

The output variable is sized according to the length of the encoded data (lenin), the encryption algorithm used and the encoding used for the output data.

The following considerations apply to the calculation of the length of data to encrypt (lenin, calculated in bytes):

- if no normalization is performed:
  - lenin = &string_length(data) in Ansi generation,
  - lenin = &string_length(data) * 2 in Unicode or Java generation (2 bytes per character).

- if the *NORMALIZE option is specified, lenin is between &string_length(data) and &string_length(data) * 3, according to the size of the UTF-8 characters.

The output binary data size corresponds to a whole number of blocks, with the block size depending on the chosen algorithm.

The binary data size is therefore lenout ((lenin / block_size) + 1) * block_size. For the AES algorithm, the block size is 16 bytes.

The Adelia output variable must be able to contain the encoded binary data either in hex (lenout * 2) or base 64 (maximum (4 * lenout / 3) + 3).

Specific feature of the RSA algorithm.

Caution: the RSA algorithm is not a block encryption algorithm. It can only encrypt a single data block which is the same size as the key.

On the other hand, the padding algorithm adds characters at the end of the block.

With a key size of 1024 bits and the default padding algorithm, the maximum size of data to encode is 117 characters (128 - 11).

Considerations relating to execution platforms.

Encryption function support (encryption algorithms available, maximum size of encryption keys) varies according to the platform and applicable legislation.

See the Encryption support according to the platform page for further information.