x

The _aes() function is used to encode and decode a value using the Advanced Encryption Standard (AES) with salt. This function uses the following format:

_aes(action,key,data [,keylength,encoding,[,iterations]]

action (required)	keyword	The action to be performed. Specify one of the following actions: encrypt. Encrypt the input using a generated salt. decrypt. Decrypt the input by removing the salt.
key (required)	string	The key to be used. Each character encodes 8 bits of the key and therefore must be between 0 and 255 inclusive.
data (required)	string	The input data to be encrypted or decrypted.
keylength (optional)	integer	The size of the key in bits. The following are the sizes that are supported: 128. A 128-bit key. This is the default size. 192. A 192-bit key, which requires the proper policy files. 256. A 256-bit key, which requires the proper policy files.
encoding (optional)	string	The type of encoding that will be used to convert data from characters to bytes. The default is UTF-8.
iterations (optional)	integer	The number of algorithm iterations (1...255). The default is 1.

Advanced Encryption Standard (AES) is an encryption standard adopted by the U.S. government in 2002. Implementations of AES are available in many encryption packages. Details on AES are beyond the scope of this manual but can be found in many sources of cryptographic information.

AES supports key strengths of 128 (the server default), 192, and 256 bits. Due to import-control restrictions imposed by some countries, the default jurisdiction policy files only permit strong cryptography to be used. An unlimited strength version of these files (that is, with no restrictions on cryptographic strength) is available but is not distributed by iWay.

AES is a block cypher that encrypts and then reencrypts. Any number of iterations can be entered, and the more iterations used, the higher the cryptographic strength of the result. However, this must be balanced against the processor overhead.

The key is entered as an iFL string, and can contain up to 16, 24, or 32 characters. Each character must have a value below 256. Use of escaped literals of iRL, such as use of Unicode values or hex values enable entry of complex keys. Keys shorter than the specified lengths will be padded with binary zero.

aes('encrypt','iway software','aes')
BtJLII90UBV7wtsrpN8TDw==
_aes('decrypt','iway software','BtJLII90UBV7wtsrpN8TDw==')
aes

It may be convenient to store the key in a properties file or a special register. It is recommended that the key not be hard coded in the function call. A common way to do this is to configure a register using the iWay console, or to add to a startup script:

set register mykey _concat('secret key\x01')

The _concat function is used because the iFL optimizers would not recognize the literal 'secret key\x01' and would not convert the hexadecimal escape. Using the _concat() function causes the iFL interpreter to evaluate the literal to produce the 11 character key. This will be padded with five binary zeros by the system (assuming 128 bit keys).

Alternatively, you can store the key in the internally masked form used by iSM. You can create a key of this form using the _encr() function, or using the set property command. For example:

set property keyfile mykey mysecret -encrypt

This command will generate a property file that holds the following key:

mysecret=ENCR(3237310127231613138296)

If this value is loaded into an iSM configuration register during system startup, the value will never appear in its unmasked form. For more information, see the iWay Service Manager Security Guide.

x

_hasrole(name)

name

string

The name of an authority to be tested.

The current Principal is tested for the names authority. If the user represented by this Principal has the identified authority the function returns true.

x

_getprin(keyword)

keyword

string

Keyword of which information is to be obtained. user. User name. password. Password of the user.

The information associated with the current Principal is returned. A common use of this information is to configure an emitter that inherits the login credentials of the current user.

This function returns auto when the principals are not configured on the server and the default user is used. Otherwise, the principal on the channel is returned.

x

_encr(value)

value

string

Term to encrypt

iWay Service Manager (iSM) uses a simple cryptographic mechanism to mask passwords stored in its configuration files. The algorithm employs random seeds and salting when generating the encrypted result. The result is marked with functional braces for recognition by the internal decryption services when the value needs to be used.

iWay strongly recommends that this function not be used to protect values in business systems. Facilities to use validated PKI and session key cryptography are readily available for this purpose. The use of this function should be restricted only to password masking and similar purposes. For example:

_encr(‘iway’)

This command will generate the following masked value:

ENCR(3157318131043128321832252993249)

Key generation for functions such as AES encryption can use masked values, which are unmasked only when used. A masked value can be written to a property file by using the set property command. Often that value is loaded during startup into a general register, where it continues to be carried in masked form. For more information on using the set property command, see the iWay Service Manager User's Guide.

x

_md5 (term [,term*])

term

string

A value to be added to the hash.

In cryptography, MD5 (Message-Digest algorithm 5) is a widely used cryptographic hash function with a 128-bit hash value. MD5 confirms to an Internet standard (RFC 1321). MD5 has been employed in a wide variety of security applications, and is also commonly used to check the integrity of files. An MD5 hash is typically expressed as a 32-digit hexadecimal number. Unlike functions, such as _uuid() that generate unique numbers, an MD5 hash will produce the same value given identical input. The iWay functional language enables generation of an MD5 hash of from one to nine terms.

_md5('username','realm','password')

returns

66999343281B2624585FD58CC9D36DFC

A standard use of MD5 is in digest authorization in HTTP. In this case, the username, password, a realm name and a set of random values called nonces are used to generate the hash.

Commonly in iWay, it is useful to add a hash value to a message or to check it on receipt. The _md5 function can help with this requirement.

x

_sha1(term [,term*])

term

string

Term to include in the SHA1 computation.

The SHA (Secure Hash Algorithm) hash1 functions is a cryptographic hash function designed by the National Security Agency (NSA) and published by the NIST as a U.S. Federal Information Processing Standard.

Although some concern has been raised about the absolute cryptographic security of the SHA1 algorithm, it remains a commonly used hash for securing the value of data.

For example:

_sha1('name','digest','password','1234567')

The following is returned:

95e760b78aaa4ccca9ac94b8815e753674bafaa7