/ 
Crypt-Tea-2.04
River stage zero No dependents
/ Crypt::Tea

NAME

Tea.pm - The Tiny Encryption Algorithm in Perl and JavaScript

SYNOPSIS

Usage:

use Crypt::Tea;
$key = 'PUFgob$*LKDF D)(F IDD&P?/';
$ascii_ciphertext = &encrypt ($plaintext, $key);
...
$plaintext_again = &decrypt ($ascii_ciphertext, $key);
...
$signature = &asciidigest ($text);

In CGI scripts:

use Crypt::Tea;
print &tea_in_javascript;  # now the browser can
# encrypt and decrypt ! see below for examples ...

DESCRIPTION

This module implements TEA, the Tiny Encryption Algorithm, and some Modes of Use, in Perl and JavaScript.

The $key is a sufficiently longish string; at least 17 random 8-bit bytes for single encryption.

Version 2.04, #COMMENT#

(c) Peter J Billam 1998

SUBROUTINES

encrypt( $plaintext, $key );

Encrypts with CBC (Cipher Block Chaining)

decrypt( $ciphertext, $key );

Decrypts with CBC (Cipher Block Chaining)

binary2ascii( $a_binary_string );

Provides an ascii text encoding of the binary argument. If Tea.pm is not being invoked from a GCI script, the ascii is split into lines of 72 characters.

ascii2binary( $an_ascii_string );

Provides the binary original of an ascii text encoding.

asciidigest( $a_string );

Returns an asciified binary signature of the argument.

tea_in_javascript();

Returns a compatible implementation of TEA in JavaScript, for use in CGI scripts to communicate with browsers.

JAVASCRIPT

Of course the same Key must be used by the Perl on the server and by the JavaScript in the browser, and of course you don't want to transmit the Key in cleartext between them. Let's assume you've already asked the user to fill in a form asking for their Username. This username can be transmitted back and forth in cleartext as an ordinary form variable.

On the server, typically you will retrieve the Key from a database of some sort, for example:

dbmopen %keys, '/home/wherever/passwords';
$key = $keys{$username};
dbmclose %keys;
$ciphertext = &encrypt ($plaintext, $key);

At the browser end there are various ways of doing it. Easiest is to ask the user for their password every time they submit a form or view an encrypted page.

print <<EOT;
<SCRIPT LANGUAGE="JavaScript"> <!--
key = prompt("Password ?","");
document.write(decrypt("$ciphertext", key));
// -->
</SCRIPT>
EOT

If you want the browser to remember its key from page to page, to form a session, then things get harder. If you store the Key in a Cookie, then it is vulnerable to any imposter server who imitates your IP address, and also to anyone who sits down at the user's computer.

The alternative is to store the Key in a JavaScript variable, but unfortunately all JavaScript variables get anihilated when you load a new page into the same target frame. Therefore you have to store the Key in a JavaScript variable in a frameset, open up a subframe covering almost all the screen, and load the subsequent pages into that subframe; they can then use parent.key to encrypt and decrypt. See CGI::Htauth.pm for attempts to use this kind of technique.

ROADMAP

Version 1.45 will probably remain the final version in the 1.xx branch; it is stable, and fully compatible with earlier versions. Unfortunately, the '+' character it used in the ascii-encoding is a reserved character in the query part of URLs; therefore versions 2.xx use '-' instead. Versions 2.xx can decrypt files encrypted by 1.xx, and version 1.45 can decrypt files encrypted by versions 2.xx. However, the digest (signature) functions of 1.xx and 2.xx differ in their use of '+' and '-' characters respectively.

Crypt::Tea can conflict with a similarly-named Crypt::TEA by Abhijit Menon-Sen. The functionality of Crypt::Tea is different from Abhijit's Crypt::TEA; here the encryption is done in pure Perl, all cyphertext is ascii-encoded, and notably there is a subroutine to return JavaScript code which implements compatible functions. Unfortunately, Microsoft operating systems confuse the two names and are unable to install both. Therefore, after version 2.xx, further development in Crypt::Tea will take place under the name Crypt::Tea_PPJS.

AUTHOR

Peter J Billam ( http://www.pjb.com.au/comp/contact.html ).

CREDITS

Based on TEA, as described in http://www.cl.cam.ac.uk/ftp/papers/djw-rmn/djw-rmn-tea.html , and on some help from Applied Cryptography by Bruce Schneier as regards the modes of use. Thanks also to Neil Watkiss for the MakeMaker packaging, and to Scott Harrison for suggesting workarounds for MacOS 10.2 browsers, and to Morgan Burke for pointing out the problem with URL query strings.

SEE ALSO

http://www.pjb.com.au/comp, CGI::Htauth.pm, tea(1), perl(1).