Table of Contents

# $EPIC: xform.txt,v 1.10 2012/07/04 06:30:23 jnelson Exp $

Synopsis

$xform(“<encodings>” “<metas>” <text>)

About string transformations:

The $xform() function transforms the <text> into some other form. There are three types of transformations:

Encryption Convert plain text into encrypted ciphertext
Encoding Convert any kind of data into a valid C string
Hashing Convert any kind of data into a message digest
Transcoding Convert a string between different character sets

Encryption works by taking your plain text and a password key and flipping some of the bits, which gives you output that looks like random bytes. The only way to recover the original text is to have the password key.

Because encryption usually gives you binary data, which can't be used directly in the client, you have to encode it into a usable format.

Both encryption and encoding are symmetric – they are fully reversable, and all of the information in the input data is present in the output data, but in some different way.

Hashing is different. Hashing is a form of lossy compression that takes any input data and removes all but a little bit of the information. Because is lossy compression, it is irreversable. Unlike encryption, there is no way to recover the original text from a hash.

Supported Transformations:

The xform function supports the following encryptions that all take one required argument.

Name Description Argument type
SED Simple Encrypted Data Password
BF Blowfish-CBC Password
CAST CAST5-CBC Password
AES AES256-CBC Password
AESSHA AES256-CBC with SHA256 digest of password Password
FISH Blowfish-ECB Password
DEF Default encryption (not supported yet!) Password

The xform function supports the following encodings that do not take arguments.

Name Description
URL Perform RFC3986 transformation (“URL encoding”)
ENC Perform Base-16 transformation
B64 Perform RFC1421 transformation (“Base 64”)
FISH64 Perform l64a transformation (“FiSH” ascii armoring)
CTCP Perform CTCP transformation
NONE No changes (just copies the string)
ALL Return all supported transformations (ignores the text)

The xform function supports the following transformations that take one required argument.

Name Description Argument type
ICONV Iconv charset transformation FROM/TO (see below)

The xform function supports the folowing digests:

Name Description
SHA256 SHA256 Message Digest

Description:

      $xform("<transformations>" "meta" "meta" text)

You can string together multiple transformations. Any transformation that requires a meta value (ie, a cipherkey) should be supplied after the transformations in the correct order. After this should be the plain text. To apply a transformation, prefix its name with a plus sign (“+”) and to remove a transformation, prefix its name with a minus sign (“-”). For example, +URL means url encode, and -URL means url decode.

Normally functions do not accept dwords as arguments, but xform does. If you want to do multiple transformations at once, you must separate them by spaces and surround the whole thing in double quotes. If the meta values (ie, passwords for encryption) contain spaces, you must surround the meta value with double quotes.

Iconv transformation:

For the ICONV transformation, the “meta” value is a word that contains the old encoding and the new encoding separated by a slash (“/”). There is no guaranteed list of encodings that you can use, because it depends on your system's iconv(3) facility.

Example: To convert a string from iso-8859-1 to utf8,

$xform(+ICONV "iso-8859-1/utf8" ...)

Examples:

If you want to: Then you should…
URL-encode a string $xform(+URL this is a string)
URL-decode a string $xform(-URL this%20is%20a%20string)
SED-cipher a string $xform(+SED password this is a string)
SED-decipher a string $xform(-sed password <whatever>)
Iconv transform a string from utf-8 to iso-8859-1 $xform(ICONV “utf-8/iso-8859-1” $utf8string)

More practical examples:

  1. - Read binary data from a file, encrypt it, and url encode it again.
	@fd = open(file.txt R)
	@data = read($fd 1024)
	@cipher = xform("-CTCP +SED +URL" password $data)
	@close($fd)
	msg someone $cipher

Why does this work?

  1. - $read() returns ctcp-enquoted data, so -CTCP removes it
  2. - Now we have binary data, so +SED will cipher it
  3. - Now we have ciphertext, so +URL will url encode it.

We can send this to someone else, and they can put it in $cipher…

	@newfd = open(newfile.txt W)
	@newdata = xform("-URL -SED +CTCP" password $cipher)
	@writeb($newfd $newdata)
	@close($newfd)

We did the reverse of the above:

  1. - We -URL to recover the binary data
  2. - We -SED to decrypt it using the password
  3. - We +CTCP to put it in a form we can use with $writeb().

Viola!