User Tools

Site Tools


xform

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

xform [2012/07/04 06:30] (current)
Line 1: Line 1:
 +# $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 [[what is a word|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:
 +  -- Read binary data from a file, encrypt it, and url encode it again.
 +<​file>​
 + @fd = open(file.txt R)
 + @data = read($fd 1024)
 + @cipher = xform("​-CTCP +SED +URL" password $data)
 + @close($fd)
 + msg someone $cipher
 +</​file>​
 +
 +Why does this work?
 +  -- $read() returns ctcp-enquoted data, so -CTCP removes it
 +  -- Now we have binary data, so +SED will cipher it
 +  -- Now we have ciphertext, so +URL will url encode it.
 +
 +We can send this to someone else, and they can put it in $cipher...
 +<​file>​
 + @newfd = open(newfile.txt W)
 + @newdata = xform("​-URL -SED +CTCP" password $cipher)
 + @writeb($newfd $newdata)
 + @close($newfd)
 +</​file>​
 +
 +We did the reverse of the above:
 +  -- We -URL to recover the binary data
 +  -- We -SED to decrypt it using the password
 +  -- We +CTCP to put it in a form we can use with $writeb().
 +
 +Viola!
 +
  
xform.txt ยท Last modified: 2012/07/04 06:30 (external edit)