GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  CRYPT::TEA (3)

.ds Aq ’

NAME

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

CONTENTS

SYNOPSIS

Usage:



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



In CGI scripts:



 use Crypt::Tea;
 print &tea_in_javascript;
 # now the browser can encrypt and decrypt ! In JS:
 var ascii_ciphertext = encrypt (plaintext, key);
 var plaintext_again  = decrypt (ascii_ciphertext, key);
 var signature = asciidigest (text);



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.12, #COMMENT#

(c) Peter J Billam 1998

SUBROUTINES

encrypt( $plaintext, $key ); Encrypts with CBC (Cypher Block Chaining)
decrypt( $cyphertext, $key ); Decrypts with CBC (Cypher Block Chaining)
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.

EXPORT_OK SUBROUTINES

The following routines are not exported by default, but are exported under the ALL tag, so if you need them you should:



 import Crypt::Tea qw(:ALL);



binary2ascii( $a_binary_string ); Provides an ascii text encoding of the binary argument. If Tea.pm is not being invoked from a CGI script (as judged by the existence of $ENV{REMOTE_ADDR}), the ascii is split into lines of 72 characters.
ascii2binary( $an_ascii_string ); Provides the binary original of an ascii text encoding.

JAVASCRIPT

At the browser end, the following functions offer the same functionality as their perl equivalents above:
encrypt ( str, keystr )
decrypt ( ascii, keystr )
asciidigest ( str );
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, and that 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:



 $plaintext = "<P>Hello World !</P>\n";
 dbmopen %keys, "/home/wherever/passwords";
 $key = $keys{$username};
 dbmclose %keys;
 $cyphertext = &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 view an encrypted page, or submit a form.



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



To submit an encrypted FORM, the neatest way is to contruct two FORMs; one overt one which the user fills in but which never actually gets submitted, and one covert one which will hold the cyphertext.



 print <<EOT;
 <SCRIPT LANGUAGE="JavaScript"> <!--
 function submitter (form) { // NB: a javascript: url passes the frame
   var plaintext = "";
   for (var i=0; i<form.length; i++) { // construct ff-separated list
     var e = form.elements[i];
     plaintext += (e.name+"\f"+ e.value+"\f");
   }
   document.covert.cyphertext.value = encrypt (plaintext, key);
   document.covert.submit();   // submit the covert form
   return false;  // dont actually submit the overt form
 }
 // -->
 </SCRIPT>
 EOT

 print <<EOT;
 <FORM NAME="covert" ACTION="$ENV{SCRIPT_NAME}" METHOD="post">
 <INPUT TYPE="hidden" NAME="username" VALUE="$username">
 <INPUT TYPE="hidden" NAME="cyphertext" VALUE="">
 </FORM>

 <FORM NAME="overt" onSubmit="return submitter(this)">
 <TABLE>
 <TR><TH>Contact</TH><TD><INPUT TYPE="text" NAME="contact"></TD></TR>
 <TR><TH>Date   </TH><TD><INPUT TYPE="text" NAME="date">   </TD></TR>
 <TR><TH>Report </TH><TD><INPUT TYPE="text" NAME="report"> </TD></TR>
 </TABLE>
 <INPUT TYPE="submit">
 </FORM>
 EOT



See the cgi script examples/tea_demo.cgi in the distribution directory.

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, it is vulnerable to any imposter server who imitates your IP address, and also to anyone who sits down at the user’s computer. However, this remains the most practical option.

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. This can become intractable. See CGI::Htauth.pm for attempts to use this kind of technique.

BROWSERS

Crypt::Tea works fine with most browsers. You can check out yours by viewing the test page test.html which is generated in the install directory when you run perl test.pl or make test. If you can read the paragraphs at the end, then everything works.

There is believed to be a problem with MacOS 10.2 Safari and IE browsers, in which binary operations like xor and shift mess up the leftmost bit of the word. The work-around would probably be to re-implement these machine instructions in JavaScript :-(

There is believed to be some problem in the core functions tea_code and tea_decode on the version of Konqueror reporting itself as Konqueror 5.0 (compatible; Konqueror/3.1; Linux) although the very similar Konqueror 5.0 (compatible; Konqueror/3.2; Linux) works fine.

ROADMAP

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. Version 1.45 will remain the final version in the 1.xx branch; the ’+’ character it used in the ascii-encoding is a reserved character in the query part of URLs.

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.

This version (2.11) is mature, and apart perhaps from minor bug fixes it will probably be the final version of Crypt::Tea. Further development will take place probably under the name Crypt::Tea_JS.

Crypt::Tea_JS will use some C for extra speed, and will use the new version of the TEA algorithm. The calling interface will be identical. Backward compatibility will be available for files encrypted with Crypt::Tea, but it will not be the default.

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, to Morgan Burke for pointing out the problem with URL query strings, and to Rolf Wagner for testing.

SEE ALSO

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

POD ERRORS

Hey! <B>The above document had some coding errors, which are explained below:B>
Around line 648: You forgot a ’=back’ before ’=head1’
Around line 655: ’=item’ outside of any ’=over’
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 TEA (3) 2006-08-28

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.