no way to compare when less than two revisions

Differences

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

@@ 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!