[Mac_crypto] Lucrative: A web service package for digital bearer instrument issuance.

R. A. Hettinga mac_crypto@vmeng.com
Sat, 15 Feb 2003 22:32:59 -0500
Previous message: [Mac_crypto] Open Source Digital Bearer Certificate Mint/Walletware Released (was re: a lucrative enterprise)
Next message: [Mac_crypto] Java/Axis/MySQL/JDOM/0SX Volunteer for IBUC needed
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
http://lucrative.thirdhost.com/README.txt 



LUCRATIVE

A web service package for digital bearer instrument issuance. 

This third preview release exposes a SOAP interface for Ben Laurie's Lucre project digital coin protocol, and a few other tools.

For more information and an up to date copy of this software, visit http://lucrative.thirdhost.com/ 



VISION

I would like to see this become an out-of-the-box digital cash solution, where it would take only minutes or hours to setup the software portion of a new enterprise. I believe an informally standardized compound document format for digital bearer instruments will greatly ease the adoption of this technology.



STATUS

This is a pre-release; more of an appetizer than the main course. It's rough around the edges, and no APIs are locked down yet.

This release builds on Ben Laurie's Java source code. Since I am not a cryptographer by training, I avoided changing the 'core' crypto code as much as possible. 

To reiterate, don't try to start a commercial enterprise yet! This package needs several things: 
- thread safety
- an accounts management API
- a fully functional interactive client
- series expiration, key rotation.
- microcharges for transactions (there is no support for fees as yet) - jar package, binary/source distributions, etc. - and more


PLANS

Well, there's so little to do, and so much time! Wait... strike that, reverse it. 


INSTALLATION

Server Requirements:

Java JDK 1.4+ (http://java.sun.com)
Axis 1.1b (http://ws.apache.org/axis/)
MySQL Connector-J or other JDBC driver (http://www.mysql.com/products/connector-j/index.html) 
MySQL or other database (http://www.mysql.com/) JDOM b8 (http://www.jdom.org/)

Client Requirements:
Java JDK 1.4+ (http://java.sun.com)
Axis 1.1b (http://ws.apache.org/axis/)
JDOM b8 (http://www.jdom.org/)

Server Installation:
(These instructions are for the Axis standalone SOAP server, included with Axis. Other SOAP servers may work too; Apache Tomcat 4.1.18 does.) 

* Make sure you have all the requirements listed. 

* Unzip the distribution.

* Set your classpath to include all these jars: 

AXIS: 	axis.jar, commons-discovery.jar, commons-logging.jar, jaxrpc.jar, 			saaj.jar, log4j-1.2.4.jar
MYSQL Connector-J:	mysql-connector-java-2.0.14-bin.jar 
 JDOM:	jdom.jar

as well as the local directory "."

* Go to CONFIGURATION, below.


* cd to the distribution directory 'java', i.e., 	cd lucre
	cd java

* build the WSDL for your local machine: 	java org.apache.axis.wsdl.Java2WSDL -o lucrative.wsdl -l"http://localhost:8080/axis/services/LucrativeServer" -n"urn:LucrativeServer" -p"org.lucrative" "urn:Lucrative" org.lucrative.LucrativeServerImpl 

* build the Java connective code for that wsdl file: 	java org.apache.axis.wsdl.WSDL2Java -o . -d Session -s -S true -Nurn:Lucrative org.lucrative lucrative.wsdl 

	(You may get a warning like 'LucrativeServerSoapBindingImpl.java already exists, WSDL2Java will not overwrite it.' 	This is expected.)

* build all project sources. I use NetBean 3.4.1. 

* start the Axis SOAP server:
	java org.apache.axis.transport.http.SimpleAxisServer 

* in another window in the same directory, deploy the service: 	java org.apache.axis.client.AdminClient LucrativeServer\deploy.wsdd 

* run the SOAP client test:
	java org.lucrative.client.Client


INSTALLATION COMMENTS:

	mids@invisiblenet.net has mentioned:
	Setting my CLASSPATH to those files o/r 	JAVA_ENDORSED_DIRS to the directories didn't work, so I copied them to /usr/local/j2sdk1.4.1_01/jre/lib/ext 


CONFIGURATION

* Configure logging options: optionally, edit lucrelog.properties as appropriate. (These properties are referenced in org.lucrative.accounts.DataStore) 

* You'll need to setup the database as well. A MySQL dump is included in the file "mysql.dump". Import or run this file with a MySQL client to setup the tables and seed some test data. 

[Schema Note: 'active' fields are ignored for this release. Accounts can have an arbitrary number of Balances, each of which represents an asset type, such as "silver ounces" or "heads of cattle" or "gold grams". Series encapsulate all the information about a digital bearer instrument currency type, such as '0.05 grams of gold, issued by FirstLucreBank, using the keyset (g,p,public,private)'. I believe this is roughly analogous to a "US 1965 five cent coin".] 

[Schema note: the 'pgpkey' field is currently ignored.] 


The MySQL dump creates a master account for the digital coin system to store assets in: "21360886c74e070220553f1e8b9c2de497ac890e" 

And it creates an account for your client to draws coins from: "4c4ac4d69679e8f562fb4d70918dd3dcc7375c95", password is: shflubnliuliuherlbher 

To generate your own passwords run the java class ord.lucrative.util.Hash: 
> java org.lucrative.util.Hash passwordtohash 
 Lucrative uses the SHA-1 algorithm, then base64 encodes the result. 

* Edit dao.properties as appropriate. This is where you setup database and driver information for Lucrative. (These properties are referenced in org.lucrative.accounts.DataStore) 


USE, TESTING

The wsdl file is in LucrativeServer/. A SOAP client is in org.lucrative.client. 

If you don't want to deploy the web service, the org.lucrative.client.LocalClient class has a main method that accesses the server libraries directly. 

If you've used Ben Laurie's Lucre distribution, the Implementation class's main method should still work. Note that I renamed the package to org.lucrative; I did this because I was unsure whether the old package name contained a trademark and whether permission was granted to redistribute that package name.

There is a tool to create your own Series: 	java org.lucrative.client.SeriesMaker
	(Run the class with no arguments for basic instructions.) 



THE CLIENTS

Three clients are included with this release: 

org.lucrative.client.Client -- An interface testing client run from the command line. From the command line, run
	java org.lucrative.client.Client


org.lucrative.client.LocalClient -- An interface testing client run from the command line, 	this tool does not use the SOAP interface but calls the LucrativeServer API directly. This 	is useful for isolating problems, as the server's OUT and ERR streams write to LocalClient's 	output.
>From the command line, run
	java org.lucrative.client.LocalClient


org.lucrative.client.cashbox.CashBox
	CashBox is the interactive client included with this release. It is a quick-and-dirty GUI client that demonstrates the basic operations of managing a coin purse. It still needs a lot of work but it is functional and should give you some ideas. 

	Screenshots of CashBox in action are on the website, http://lucrative.thirdhost.com/. 

>From the command line, run
	java org.lucrative.client.cashbox.CashBox 



IF YOU GET IT WORKING

Please drop me a note at: patrick@lfcgate.com. 


TODO

See: PLANS, above.


FIBIs, Format for the Interchange of Bearer Instruments 

Some XML documents are used by the client and server. The format of these documents is in flux, but they currently look like this:

Fibi Signature request:

<?xml version="1.0" encoding="UTF-8"?>
<signature_request>
<coin_request>
<coin_series>Pure Gold</coin_series>
<blinded_coin>836459079cbdc26664d3f93fe9d2c0d301c951a2d85b2344752433ef59957e5351d0563ff6b327680b594933c89e566104776ee5cb8f969b71aa1034b255b389</blinded_coin> </coin_request>
<coin_request>
<coin_series>Pure Gold</coin_series>
<blinded_coin>bba82dd20ea37707fecfbc9b764e32846dafb123866ca437eb53eb36a52ad9a42dec5278f15c9f4591c88d0d72a8fc14d25228a1322f0279bbaf96815e1cc0bf</blinded_coin> </coin_request>
<coin_request>
<coin_series>Pure Gold</coin_series>
<blinded_coin>d6d470c7e8537bbaac646976213b872bb338afea4a8a6b45f29600e5ed561ca234ff75535477657698b0f52871189a10c358852b74edd464deeefc859166b616</blinded_coin> </coin_request>
<coin_request>
<coin_series>Pure Gold</coin_series>
<blinded_coin>d47d0c020376f923be4c4d0d8c1c1542b2d279743ffc8d75880050977e4377153120eef1b5bc8d170234712b16923748c9e2253febf639b34331daff9a8d99bb</blinded_coin> </coin_request>
</signature_request>



Fibi Signature response:

<?xml version="1.0" encoding="UTF-8"?>
<signature_response>
<coin_response>
<coin_series>Pure Gold</coin_series>
<signature_request>836459079cbdc26664d3f93fe9d2c0d301c951a2d85b2344752433ef59957e5351d0563ff6b327680b594933c89e566104776ee5cb8f969b71aa1034b255b389</signature_request> <blind_signature>1fa7ed80c26ca353b2572a4e5a29505f3730a6e3d1ab635315e23fdc871f669e74e1c6390d7cd01fc55108d5f0850f95f28a374626f05689baf481dc4274e3d2</blind_signature> </coin_response>
<coin_response>
<coin_series>Pure Gold</coin_series>
<signature_request>bba82dd20ea37707fecfbc9b764e32846dafb123866ca437eb53eb36a52ad9a42dec5278f15c9f4591c88d0d72a8fc14d25228a1322f0279bbaf96815e1cc0bf</signature_request> <blind_signature>31f13ecced1338095744c36d0fe19ae6302f13c64869eca7d5eed4fe2ba80788d27411408a41c5e58e27d21ccfdf71ac2091487bf0a508b9ae6249d2bb1e5bd4</blind_signature> </coin_response>
<coin_response>
<coin_series>Pure Gold</coin_series>
<signature_request>d6d470c7e8537bbaac646976213b872bb338afea4a8a6b45f29600e5ed561ca234ff75535477657698b0f52871189a10c358852b74edd464deeefc859166b616</signature_request> <blind_signature>45fab75d36fc7a0b36b40379191838f867226f956a414acb1552eb339d5ff5a903da966ad26720115d7569143cda32a9aed2a2c7ae9a988c3c9a390449af002c</blind_signature> </coin_response>
<coin_response>
<coin_series>Pure Gold</coin_series>
<signature_request>d47d0c020376f923be4c4d0d8c1c1542b2d279743ffc8d75880050977e4377153120eef1b5bc8d170234712b16923748c9e2253febf639b34331daff9a8d99bb</signature_request> <blind_signature>2b1c319fa08050ef8420c288825b7896ff17a067807dd92fb67e680885311eb7519cae082518eac81b9f9688b8a7a11de2ec98d10add1f67be70a8ebed6e341e</blind_signature> </coin_response>
</signature_response>



Fibi Series List:
<?xml version="1.0" encoding="UTF-8"?>
<series_list>
<series>
<name>SERIALNUMBERXX1234HHHJJJKKKO</name> <public>aaf3fef02408248da27d8bf2a04cf51b355050ba6c9ab7a6905289215b05afcd</public> <g>4</g>
<p>fb68dafab8405b23b597880b8b7864620f1a95aea9c88155d5406082b140ba1b</p> <issuer>DigitalCowsLtd.</issuer>
<issuer_url>http://lucrative.thirdhost.com/</issuer_url> <amount>2.5</amount>
<unit>cow</unit>
<asset>cows</asset>
<backing_policy>fictitious</backing_policy> </series>
<series>
<name>SERIALNUMBERXX1234HHHJJJKKKP</name> <public>3c7f086685e8d5c4faad6f77ec0a9853b1db56cd67d00ec4f66a19ed1d9b878</public> <g>4</g>
<p>9c3b90a328a23c3849d342da818cfc224a98f47e47e476d1343d35dfd2e90ee7</p> <issuer>DigitalCowsLtd.</issuer>
<issuer_url>http://lucrative.thirdhost.com/</issuer_url> <amount>1.5</amount>
<unit>cow</unit>
<asset>cows</asset>
<backing_policy>fictitious</backing_policy> </series>
<series>
<name>SERIALNUMBERCRAZYPONY12345</name>
<public>b930160eeb96fa1e2ccad53e9c0d893005db8510fe8ac005a359d356f7a92762</public> <g>4</g>
<p>f01dfc34f41a554def078198252be45745350077da610d5227ad9bcfdbf787b3</p> <issuer>Demonstration Issuer</issuer>
<issuer_url>http://lucrative.thirdhost.com/</issuer_url> <amount>1.5</amount>
<unit>gram</unit>
<asset>gold</asset>
<backing_policy>fictitious</backing_policy> </series>
<series>
<name>SERIALNUMBERSILLYSPECIES12345</name> <public>d5aa8be32fc57c9761af41138ce65428724a80db9d2b39c9062c4fca3457cbd2</public> <g>4</g>
<p>e7b93653d895e561fa0910108b5a576bbb6796a660644000726c8aa6636f2ee3</p> <issuer>Demonstration Issuer</issuer>
<issuer_url>http://lucrative.thirdhost.com/</issuer_url> <amount>0.5</amount>
<unit>gram</unit>
<asset>gold</asset>
<backing_policy>fictitious</backing_policy> </series>
</series_list>


Suggestions and improvements are welcome. 



LICENSE

I have attached a (slightly modified) MIT license to the source code files and package. Please keep in mind that Ben Laurie's code comes with its own license that must be included and observed. I suppose you could remove all of Ben Laurie's code and 'clean-room' the digital coin protocol if you can't abide by his license. 

IMPORTANT NOTICE:
"This product includes software developed by Ben Laurie for use in the Lucre project." 


ACKNOWLEDGEMENTS

Much thanks to Ben Laurie for his clearly written August 22, 2002 paper and source code, and also to the cypherpunks and cryptographers who make this work possible. 

Thanks mids@invisiblenet.net for encouragement, suggestions, and installation instructions. 


Patrick

Email me with questions, comments, job offers, digital bearer instruments: patrick@lfcgate.com 

-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: PGPfreeware 6.5.3 for non-commercial use <http://www.pgp.com> 

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 TjWLDLarQxcPYhbkFi4=
=nx1M
-----END PGP PUBLIC KEY BLOCK-----

-- 
-----------------
R. A. Hettinga <mailto: rah@ibuc.com>
The Internet Bearer Underwriting Corporation <http://www.ibuc.com/>
44 Farquhar Street, Boston, MA 02131 USA
"... however it may deserve respect for its usefulness and antiquity,
[predicting the end of the world] has not been found agreeable to
experience." -- Edward Gibbon, 'Decline and Fall of the Roman Empire'
Previous message: [Mac_crypto] Open Source Digital Bearer Certificate Mint/Walletware Released (was re: a lucrative enterprise)
Next message: [Mac_crypto] Java/Axis/MySQL/JDOM/0SX Volunteer for IBUC needed
Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]