Menu
▾
▴
[Neuclear-develop] neuclear-id-sample/xdocs bdg.xml,NONE,1.1 index.xml,NONE,1.1 installation.xml,NONE,1.1
|
From: <pe...@us...> - 2003-12-16 15:04:34
|
Update of /cvsroot/neuclear/neuclear-id-sample/xdocs
In directory sc8-pr-cvs1:/tmp/cvs-serv10622/xdocs
Added Files:
bdg.xml index.xml installation.xml
Log Message:
Added SignedMessage contract for signing simple textual contracts.
Added NeuSender, updated SmtpSender and Sender to take plain email addresses (without the mailto:)
Added AbstractObjectCreationTest to make it quicker to write unit tests to verify
NamedObjectBuilder/SignedNamedObject Pairs.
Sample application has been expanded with a basic email application.
Updated docs for sample web app.
Added missing LGPL LICENSE.txt files to signer and sample app
--- NEW FILE: bdg.xml ---
<?xml version="1.0"?>
<document>
<properties>
<title>The Busy Developer's Guide to the NeuClear ID API</title>
<author email="pe...@ne...">Pelle Braendgaard</author>
</properties>
<body>
<section name="The Busy Developer's Guide to the NeuClear ID Sample Web App">
<h4>Scope</h4>
<p>
This document describes in Example form the usage of the NeuClear ID API. The Document is not intended as
an implementation document or a strict API definition. The current final API Specifications can be found in the
<a href="../apidocs/index.html">Project Java Docs</a>.
</p>
<h4>Audience</h4>
<p>
The audience for this developers guide are expected to be relatively familiar with Java. The instructions are
currently listed for unix type machines, but it should work on any machine running jdk1.4 including Windows.
</p>
<h4>Purpose</h4>
<p>
The main purpose of the NeuClear ID API is to provide a simple framework and API for building applications
using a Public Key Infrastructure (PKI).
</p>
</section>
<section name="Creating an Top Level Identity for your Domain Name">
<p>
All messages (
<a href="apidocs/org/neuclear/id/SignedNamedObject.html">SignedNamedObjects</a> in NeuClear lingo)
in NeuClear ID must be signed by an
<a href="apidocs/org/neuclear/id/Identity.html">Identity</a>. So to get started we
must first create a new Identity.
</p>
<p>
Each domain name must create a top level identity, which main job in life is to sign sub identities. So that is where we start.
</p>
<p>
The easiest way to get started is to use the neuclear-id-app.jar from a command line.
We need to have the following ready:
</p>
<ul>
<li>The Name</li>
<li>A default receiver</li>
<li>A RSA Key Pair</li>
</ul>
<h4>Pick an Identity Name</h4>
<p>
As we first need to create a top level Identity for your domain we will use the name neu://yourdomain.com as the
Identity name. For now to keep things simple lets use your email address as the default receiver.
</p>
<h4>Creating the Key Pair</h4>
<p>
Now we know the name of our new identity we first need to create our keypair. Sun provides us with a very badly designed
tool called
<a href="http://java.sun.com/j2se/1.4.2/docs/tooldocs/solaris/keytool.html">keytool</a> which we can use to
create and store our keypair. The NeuClear toolset will provide its own keygeneration tools soon, but for now we've got to do it like this:
</p>
<source>$ keytool -genkey -keyalg RSA -alias
<b>neu://yourdomain.com</b>
Enter keystore password: #####
What is your first and last name?
[Unknown]:
<b>neu://yourdomain.com</b>
What is the name of your organizational unit?
[Unknown]: Your Domain
What is the name of your organization?
[Unknown]: Your Domain
What is the name of your City or Locality?
[Unknown]: Panama City
What is the name of your State or Province?
[Unknown]: Panama
What is the two-letter country code for this unit?
[Unknown]: PA
Is CN=neu://yourdomain.com, OU=Your Domain, O=Your Domain, L=Panama City, ST=Panama, C=PA correct?
[no]: yes
Enter key password for neu://yourdomain.com
(RETURN if same as keystore password):
</source>
<p>
What you can see there is the invocation of keytool with the
<tt>-genkey</tt> option.
We pick a RSA key, which is recommended over the default DSA key. The alias must be the same as the ID that you are creating.
The details about first and last name location etc, are pretty much irrelevant for our purposes, but by convension we like to
put the ID (eg.
<tt>neu://yourdomain.com</tt>) in the first and last name field. What might not be immediately obvious here
is that keytool creates a default keystore in your home directory at
<tt>~/.keystore</tt> this contains your keys and the
neuclear tools use this keystore later on.
</p>
<h4>Create the Selfsigned Certificate</h4>
<p>
Download the
<a href="http://neuclear.org/maven/neuclear-id/jars/neuclear-id-app-0.8.jar">NeuClear ID Executable</a>.
Excuse the long and ugly name, we will package it nicer later on. Currently this tool allows you to create a certificate and
sign it. Lets run it with our ID and receiver we decided on earlier.
</p>
<source>$ java -jar neuclear-id-app-0.8.jar --name neu://yourdomain.com --receiver mailto:ad...@yo...
Please enter passphrase for: KeyStore Passphrase for~/.keystore
:
Signing by neu://yourdomain.com ...
Please enter passphrase for: neu://yourdomain.com
:
Outputting to: _NEUID/yourdomain.com/root.id</source>
<p>
The program asks you for the passphrases for both the keystore and your key. Enter them exactly like you did
before.
</p>
<h4>Copy certificate to Web Server</h4>
<p>
The Certificate must now be moved to your web server. It has to live in the following file:
<tt>http://yourdomain.com/_NEUID/yourdomain.com/root.id</tt>
<br/>
The simplest way to do this in unix is to use
<tt>scp</tt>:
</p>
<source>scp -r _NEUID/
<b>us...@yo...:/home/httpd/htdocs/</b>
</source>
<p>
where
<tt>user</tt> is your username on the webserver.
<tt>yourdomain.com</tt> is webserver domain name and
<tt>/home/httpd/htdocs/</tt> the full absolute path to the root of your web server.
</p>
</section>
<section name="Test your Identity">
<p>
To verify an Identity type the following in your command prompt:
</p>
<source>$ java -jar neuclear-id-app-0.8.jar --verify neu://pelle@neuclear.org
Resolving and Verifying: neu://pelle@neuclear.org
Signed Object: neu://pelle@neuclear.org is verified
was signed at: 2003-12-09T10:00:42,466EST
Is of type: org.neuclear.id.Identity
repository: http://neuclear.org/_NEUID
signer: http://localhost:11870/Signer</source>
<p>
Try it with your new identity that you created above.
</p>
</section>
<section name="Creating a Sub Identity">
<p>
We dont recommend using top level identities for anything but signing sub identities. So for us to actually get started on some
real fun we need to create a new sub identity. This is pretty much a repitition of the above, so I will just highlight the differences
here.
</p>
<h4>Chosing the name</h4>
<p>
By convention there are two ways you can name a sub identity. For individuals or roles use the familiar email naming
convention. Such as:
</p>
<ul>
<li>
<tt>neu://bob@yourdomain.com</tt>
</li>
<li>
<tt>neu://sales@yourdomain.com</tt>
</li>
</ul>
<p>
If you want your sub identity to be a process or service. Such as an ecommerce site, an asset transfer system or an exchange system use
this format:
</p>
<ul>
<li>
<tt>neu://yourdomain.com/store</tt>
</li>
<li>
<tt>neu://yourdomain.com/homebanking</tt>
</li>
</ul>
<p>
The two formats are functionally equivalent, but are separated stylistically to make it easier to understand for
end users.
</p>
<p>
So for our example we picked
<tt>neu://bob@yourdomain.com</tt>
</p>
<h4>Creating the Key Pair</h4>
<p>
Create a new keypair just like you did before:
</p>
<source>$ keytool -genkey -keyalg RSA -alias
<b>neu://bob@yourdomain.com</b>
Enter keystore password: #####
What is your first and last name?
[Unknown]:
<b>neu://bob@yourdomain.com</b>
What is the name of your organizational unit?
[Unknown]: Your Domain
What is the name of your organization?
[Unknown]: Your Domain
What is the name of your City or Locality?
[Unknown]: Panama City
What is the name of your State or Province?
[Unknown]: Panama
What is the two-letter country code for this unit?
[Unknown]: PA
Is CN=neu://bob@yourdomain.com, OU=Your Domain, O=Your Domain, L=Panama City, ST=Panama, C=PA correct?
[no]: yes
Enter key password for neu://bob@yourdomain.com
(RETURN if same as keystore password):
</source>
<h4>Create the Signed Certificate</h4>
<p>
Again we need to create a certificate. This time however it is not self signed, but signed
by the top level identity we created above. As long as we create the two identities on the same
machine. The process is completely identical from a users stand point, with the notable exception
that we are asked for the root identity's passphrase and not the one of the sub identity.
</p>
<source>$ java -jar neuclear-id-app-0.8.jar --name neu://bob@yourdomain.com --receiver mailto:bo...@yo...
Please enter passphrase for: KeyStore Passphrase for~/.keystore
:
Signing by neu://yourdomain.com ...
Please enter passphrase for: neu://yourdomain.com
:
Outputting to: _NEUID/yourdomain.com/@bob/root.id</source>
<p>
Now all that remains is to copy it to your web server exactly like you did above and your new sub identity is
ready and live.
</p>
</section>
<section name="Signing and verifying messages">
<p>
Coming soon.
</p>
</section>
</body>
</document>
--- NEW FILE: index.xml ---
<?xml version="1.0"?>
<document>
<properties>
<title>NeuClear - ID</title>
<author email="pe...@ne...">Pelle Braendgaard</author>
</properties>
<body>
<section name="Introduction">
<p>
This is a sample web application for demonstrating how simple it is to write applications that utilize
<a href="http://neuclear.org/id/">NeuClear ID</a>. The main functionality allows users to log in to the
application using their NeuClear ID and then send signed messages to other people.
</p>
</section>
<section name="Busy Developer Guide">
<p>
To get started view the <a href="bdg.html">busy developers guide</a>. Aimed to get developers started
with their own site quickly and easily.
</p>
</section>
</body>
</document>
--- NEW FILE: installation.xml ---
<?xml version="1.0"?>
<document>
<properties>
<title>Installing</title>
<author email="pe...@ne...">Pelle Braendgaard</author>
</properties>
<body>
<section name="Requirements">
<p>
Any JRE 1.4 VM should work.
<a href="http://www.java.com:80/en/download/manual.jsp">Get the latest for your platform straight from Sun</a>.
If you are running Mac OS/X Jaguar or Panther you should already be set. Please let us know of any problems.
</p>
<p>
For deployment you need a J2EE appserver, that supports version 2.3 of the Servlet API.
In tomcat you can simply drop it into the <tt>$CATALINA_HOME/webapps</tt> folder.
</p>
<p>
For more information see the <a href="bdg.html">Busy Developers Guide</a>.
</p>
</section>
</body>
</document>
|
