$Id: README,v 1.23 2004/11/26 18:41:47 jay Exp $

cryptopp-php -- a PHP crypto extension using Crypto++
Version 0.0.15.

J Smith <dark_panda@hushmail.com>
26 Nov 2004

0. What is it?

	cryptopp is simply an extension for PHP that provides two-way cryptography
	and one-way hashes using the public domain Crypto++ library by Wei Dai et
	al.
	
	Crypto++ can be found at
	
		http://www.eskimo.com/~weidai/cryptlib.html


1. What's wrong with the mcrypt and mhash extensions already available for PHP?

	Nothing. They're fine, and they work well. The motivation behind this
	extension wasn't to provide a PHP extension that would supplant mcrypt/hash,
	but rather to provide an alternative.
	
	Originally, the motivation behind this extension stemmed from the need for
	a cryptography library that could be used with PHP and with plugins for
	Microsoft's Windows Media Player. I work for a company that provides online
	educational videos via WMS, and we needed a crypto API that would work on
	both win32 platforms (for a WMS plugin) and on UNIX platforms with PHP (to
	provide ciphertext, which the plugin would decrypt).
	
	Unfortunately, the native win32 ports of libmcrypt and libmhash are 
	apparently no longer maintained, and cygwin is required to build on
	Windows. This sucks, as cygwin would be a ridiculous dependency for a
	simple WMS plugin.
	
	The cryptopp extension for PHP was created in an effort to provide a
	cryptography for PHP that would work on both UNIX and win32 systems. 
	Hopefully.
	
	
2. What crypto algorithms, hash algorithms, etc. does the extension provide?

	The cryptopp extension provides the following block cipher algorithms:
	
		- 3Way
		- AES (a.k.a. Rijndael)
		- Blowfish
		- CAST-128
		- CAST-256
		- DES
		- DES-EDE2 (Triple DES)
		- DES-EDE3 (another form of Triple DES)
		- DES-XEX3 (xDES)
		- Diamond2
		- Diamond2Lite
		- GOST
		- IDEA
		- MARS
		- RC2
		- RC5
		- RC6
		- SAFER-K and SAFER-SK
		- Serpent
		- SHARK (on systems that provide word64)
		- SKIPJACK
		- Square
		- TEA
		- Twofish
		
	The above ciphers can be used with any of the following block cipher modes:
	
		- CBC 
		- CBC with ciphertext stealing
		- ECB
		- OFB
		- CFB
		- Counter

	ECB is the default cipher mode.

	In addition to the aforementioned block ciphers, the following stream
	ciphers are available:

		- ARC4 (the alleged RC4 algorithm)
		- MARC4 (a modified ARC4 algorithm)
		- Panama (little and big endian)
		- SEAL (3.0 big and little endian)

	The following hash algorithms are currently supported:
	
		- HAVAL -- actually, HAVAL consists of four algorithms -- HAVAL,
		  HAVAL3, HAVAL4 and HAVAL5. HAVAL can produce digests of variable
		  lengths; however, this extension currently has the digest length
		  locked at 32 bytes. (64 bytes in hex.)
		- MD2
		- MD4
		- MD5
		- Panama -- two modes are available -- big endian and little endian.
		- RIPEMD160
		- SHA1
		- SHA-256
		
	The remaining hash algorithms are only available on systems that implement
	word64:
		
		- SHA-384
		- SHA-512
		- Tiger
		
	There are also two checksum algorithms available that act as non-
	cryptographic hashes:
	
		- CRC32
		- Adler32

	As of version 0.0.9, several keyed HMAC algorithms were added:

		- MD2
		- MD4
		- MD5
		- SHA1, -256, -384 and -512
		- Tiger
	

3. How do I compile the extension?

	Read the manual in docs.
    

4. How do I use the extension?
	
	See the docs directory for somewhat detailed notes.
	
	A quick example of encrypting a string, decrypting it, and hashing it
	(without any error checking):
	
	<?php
	
	$encrypt = cryptopp_create_cipher(CRYPTOPP_CIPHER_BLOWFISH);
	cryptopp_set_mode($encrypt, CRYPTOPP_MODE_CBC);
	cryptopp_set_iv($encrypt, "this is an iv", 1);
	cryptopp_set_key($encrypt, "this is a secret key");
	cryptopp_set_plaintext($encrypt, "this is some plaintext");
	cryptopp_encrypt($encrypt);
	
	// you could send this ciphertext, IV and key and such
	// to some place else for decrypting; we'll just do it here
	
	$decrypt = cryptopp_create_cipher(cryptopp_get_cipher_type($encrypt));
	cryptopp_set_mode($decrypt, cryptopp_get_mode($encrypt));
	cryptopp_set_iv($decrypt, "this is an iv", 1);
	cryptopp_set_key($decrypt, "this is a secret key");
	cryptopp_set_ciphertext($decrypt, cryptopp_get_ciphertext($encrypt));
	cryptopp_decrypt($decrypt);
	
	print "Decrypted plaintext: " . cryptopp_get_plaintext($decrypt) . "\n";
	print "Ciphertext: " . cryptopp_get_ciphertext($decrypt) . "\n";
	
	cryptopp_destroy_cipher($encrypt);
	cryptopp_destroy_cipher($decrypt);
	
	$hash = cryptopp_create_hash(CRYPTOPP_HASH_MD5);
	cryptopp_set_hash_plaintext($hash, "this should be hashed");
	cryptopp_hash($hash);
	
	if (cryptopp_get_hashtext($hash) == strtoupper(md5("this should be hashed")))
		print "Hash validated" . "\n";
	else
		print "Bad hash" . "\n";
		
	cryptopp_destroy_hash($hash);
		
	?>
	
	Which produces:
	
	Decrypted plaintext: this is some plaintext
	Ciphertext: 068239434952844928E6805F05B4375A4BA13BC331FEA737
	Hash validated


5. Where is the documentation? All that's in the docs directory is
	cryptopp.sgml.
   
	That is the documentation. You can use tools like sgml2html or
	sgml2rtf to change it into something you can work with. Look up
	sgml2html on Google or something. (I got tired of having to
	distribute the docs, so now all you get is the SGML source, which
	you can convert to whatever format you like.)


6. What needs to be done? What bugs do you know of? How can I help?

	The TODO list:
	
		- fix HAVAL to permit multiple digest sizes.
		- add public key crypto stuff, like RSA, DSA, etc. This would
		  be nice if you want to use the extension but don't need
		  OpenSSL at the same time.
		- optimize everything. This is a fairly big extension right now:
		  if you compile Crypto++ without the release settings (as most
		  people seem to do) and compile PHP with debugging symbols,
		  the PHP executable size increases by about 1.2 MB. The extension
		  is still nice and fast, though, and runs through my current
		  test suite of 360-some tests in just a few seconds. Making
		  it work on both UNIX and Windows made things messy. (Especially
		  thanks to win32's standard C++ string implementation.)
		- fix up the config.m4 file to be smarter at finding the
		  Crypto++ stuff needed. I don't have too much experience
		  working with this m4 jazz.
		- clean up the extension's directory hierarchy. I had a bad
		  time trying this earlier. Something to do with the config.m4
		  and Makefile files.
		
	Bugs that I know of:
	
		- I'd consider that HAVAL digest-size thing a bug at the moment.
		- that's it so far.
		
	Bugs should be emailed to me at my aforementioned email address.
	If you're paranoid, my public key is in the docs.
	
	If you'd like to help, please use the extension and give me some
	feedback. If you have any experience with PHP's build system and
	want to help out, I'd appreciate it.
	
