DECRYPT

User paragraph

All

Syntax

DECRYPT Algorithm Key InitVect Data Result

Description

This instruction is used to decrypt 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.
    The indicated value must correspond to the value used during encryption.
    
    For the padding definition, Adelia accepts a special ";ZeroPadding"; value which is not a standard padding.
    If this value is specified, the zero characters at the end will be deleted from the data during decryption.

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 identical to the value used during encryption.

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 encoding parameter specifies if the data to be decrypted is encoded in hexadecimal (*HEX) or base 64 (*BASE64). If nothing is specified, it is assumed that it is encoded in hexadecimal.

The *NORMALIZE parameter must be specified if the decrypted data is in UTF-8 format (i.e. if the ";normalize"; parameter was used when encrypting).

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:

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 size of the binary data to decrypt (lenin) is either &string_length(data) / 2 in hexadecimal, or in base 64 maximum ((&string_length(data) - 3) * 3) / 4.

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

• • if no normalization is performed:
    • lenout = lenin in Ansi generation,
    • lenout = lenin / 2 in Unicode generation (2 bytes per character).

• • if the *NORMALIZE option is specified, lenout is between lenin / 3 and lenin, according to the size of the UTF-8 characters.

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.

Example

* Simple AES decryption, 128-bit key, data encoded in hexadecimal

*

P_DATA = '850a66a7d16ffae18b65d810a50f09b6'

P_ALG = 'AES'

P_SECRET_KEY = '2d2086832cc2fe3fd18cb51d6c5e99a5'

DECRYPT P_ALG *KEY(P_SECRET_KEY) P_DATA *HEXA P_RESULT *NORMALIZE

P_RESULT = 'Secret data'

↑ Top of page