Revision as of 01:56, 5 January 2018

The $encode identifier allows you to encode literal text, or text in %vars or &binvars. The $encode identifier uses either Uuencode or MIME or Base32 to encode. Additionally, $encode is capable of utilizing Blowfish to encrypt the target before encoding using u/m/a encoding.

Synopsis

; encoding only
$encode(text/%var/&binvar [, btuma] [, N] )

; encryption
$encode(text/%var/&binvar, celsirznpbtuma, key[, salt/iv if s|i|r used] [,N] )

Parameters

Encoding

text/%var/&binvar The target to be encoded
b Target is a &binvar
t Target is text (this is default target type)
u Target should be encoded using Uuencode (this is default encode type)
m Target should be encoded using Mime (base64)
a Target should be encoded using Base32
N Integer Reference index for the Nth chunk (can't use without at least 1 switch)

• 'b' recognizes target is a binary variable instead of text beginning with '&'.
• 'b' returns encoded output back to the same binary variable, then the $encode identifier 'returns' N where N is the number of encoded characters returned to the binary variable. i.e. $bvar(&binvar,0). Most common usage would be to $encode as an argument to noop.
• When target is text or %variable, content is UTF-8 encoded before encoding. To prevent this, you must load text into a binary variable using 'bset -ta' then use $encode's 'b' switch to allow using that binary variable as the target.
• 'm' and 'u' encode 3 bytes into 4 printable characters, with u also prepending a length byte before each chunk of 60 encoded characters. 'a' encodes 5 bytes into 8 printable characters.
• If N is present, N=0 returns the number of chunks in the output, N >= 1 returns the Nth encoded chunk of the output or $null if N is greater than the N=0 value. N allows handling encoded output output of &binary strings too long to fit within %variables or mIRC's maximum line length.
• Chunks are 60 encoded characters for 'a' and 'm'. For 'u', chunks are length 61 including the length byte. 'a' chunks contain 7.5 groups of 5chars-into-8alphanumerics, so if the encoded text needs to be decoded in chunks instead of the entire output, $decode should decode chunks created by 'a' in groups of even numbered chunks to prevent corrupted data. Total output length is padded to be multiples of those groups of 4 or 8 printable characters plus the 'u' chunk length byte(s).

Encryption

c CBC encryption mode (c and e should not be used together)
e ECB encryption mode
l Literal key parameter used as key, instead of using hash of the key parameter. Has no effect with 'e' because 'e' always uses literal key.
s user defined 8-byte salt - Adds 16-byte header: RandomIV $+ Parameter#4. (valid only when 'c' also used)
i user defined 8-byte (IV) initialization vector (valid only when 'c' also used)
r random IV (valid only when 'c' also used)
z zero padding ( no more than 1 of z and n and p should be used at the same time)
n one and zeros
p spaces padding

Notes:

• 'N' parameter uses the same rules as non-encryption. It's an optional last parameter after those required by the presence of other switches ('ec' require <key>, 'csi' also require <salt|iv>)
• 'e' ignores 'sir', same key always encrypts identical groups of 8 plaintext bytes into the same 8 ciphertext bytes.
• 'c' default random salt allows same key to create different session-key each time salt differs.
• Salt/IV parameter is chopped to 8 bytes, and is padded with $chr(0) bytes if shorter. ASCII 128-255 are not UTF-8 encoded into byte-pairs, and codepoints 256+ are replaced by the $chr(63) question mark.
• Default 'c' encryption has 16-byte header beneath the encoding: The 8-byte string Salted__ followed by 8 'random' bytes.
• any of s|i|r disables default salt, and s|i require presence of 4th 8-char parameter
• 's' changes header to: Salted__ $+ Parameter#4 that's used as Salt in place of default random salt.
• 'r' changes header to: RandomIV $+ 8-random-bytes
• 'ir' changes header to: RandomIV $+ Parameter#4
• 'i' removes header without including IV in message
• Using 'ci' which uses CBC encryption with fixed IV and no salt, same key parameter creates identical ciphertext only to the point where 2 inputs differ.

Padding of 8-byte blocks ensures encryption sees binary message length as exact multiple of 8 and is removed by $decode after decryption:

• default if 'npz' not used: Append N=1-8 of $chr(N) i.e. 8 kinds of padding; 1 $chr(1), 2 $chr(2)'s, ..., or 8 $chr(8)'s
• 'n' Appends 1-8 bytes: $chr(128) followed by 0-7 $chr(0)'s
• 'p' Appends 1-8 bytes: each $chr(32) spaces
• 'z' Appends 1-8 bytes: each $chr(0)
• Don't use 'z' or 'p' if target plaintext can end with $chr(0)'s or spaces. $decode assumes all padding characters in last 8-byte block are padding characters, potentially shortening the decoded target.
• 'cl' or 'e' literal keys are chopped at 56 UTF-8 encoded bytes of the key parameter.

Example

Echo to the active screen the following encode text, using the Mime type:

//echo -a $encode(Hello there! This will be encoded using Mime.,m)

$encode encrypts the file then applies u/m/a coding to change binary encrypted data to text.
Decoding with matching u/m/a displays the header and cipher binary hidden beneath
//var %a $encode(text,csm,key,ParmSalt) | echo -a %a -> $decode(%a,m)

'l' switch chops the key parameter at 56 bytes which can be UTF-8 encoded to contain more bytes than reported by $len(key).
The bytes used as the key would be equivalent to the 1-56 bytes loaded into a binary variable by /bset while using the -t but not -a switches.
//bset -t &var 1 Key_Parameter
//echo -a $bvar(&var,1-56)
or the visible bytes of:
//echo -a $left($utfencode(key_parameter),56)

; Simple encrypted channel chat:
; 100% of security comes from %key because everyone knows %salt and $me and $chan
; message format: 1 flag + 8 salt + * message
; reacts only to channel messages containing only 1 word beginning with =
; sends only to channel mask, allows not-encrypted if input is $inpaste or $ctrlenter or begins with /
; min length 1 flag + 8 salt + 8-byte-block * 4/3 = 21
ON *:text:=*:#: { if (($2 != $null) || ($len($1) < 21)) return | secret_chat $1 }
ON &*:INPUT:#channel1,#channel2:{ if (($ctrlenter) || ($inpaste) || ($left($1,1))) return | secret_chat $1- | halt }
 
alias secret_chat {
  var %key Change this Shared Secret
  var %session_key $sha1($iif($event == text,$nick,$me) %key $chan)
  if ($event == text) {
    var %salt $mid($1,2,8) | var %text $decode($mid($1,10),cim,%session_key,%salt)
    echo -tcg normal # Decoded $+(<,$nick,>,:) %text
  }
  else {
    var %salt $regsubex($str(x,8),/x/g,$r(!,~)) | var %text $encode($1-,cim,%session_key,%salt)
    var %msg $+(=,%salt,%text) | msg # %msg | echo 3 -tg # Channel sees Encryption of: $1-
  }
}

Compatibility

Added: mIRC v5.8
Added on: 05 Sep 2000
Note: Unless otherwise stated, this was the date of original functionality.
Further enhancements may have been made in later versions.

See Also

• $decode