Menu
▾
▴
[Neuclear-develop] neuclear-id/xdocs bdg.xml,1.1,1.2 index.xml,1.4,1.5 installation.xml,1.2,1.3 overview.xml,1.2,1.3
|
From: <pe...@us...> - 2003-12-09 16:42:06
|
Update of /cvsroot/neuclear/neuclear-id/xdocs
In directory sc8-pr-cvs1:/tmp/cvs-serv30035/xdocs
Modified Files:
bdg.xml index.xml installation.xml overview.xml
Log Message:
First Chapter of Busy Developers Guide Written. Main documentation restructured somewhat.
Index: bdg.xml
===================================================================
RCS file: /cvsroot/neuclear/neuclear-id/xdocs/bdg.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** bdg.xml 8 Dec 2003 22:05:08 -0000 1.1
--- bdg.xml 9 Dec 2003 16:42:02 -0000 1.2
***************
*** 8,20 ****
<body>
! <section name="Introduction">
! <h3>Scope</h3>
<p>
This document describes in Example form the usage of the NeuClear ID API. The Document is not intended as
! an implemntation 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>
! <h3>Purpose</h3>
<p>
The main purpose of the NeuClear ID API is to provide a simple framework and API for building applications
--- 8,25 ----
<body>
! <section name="The Busy Developer's Guide to the NeuClear ID API">
! <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
***************
*** 22,26 ****
</p>
</section>
! <section name="Creating an Identity">
<p>
All messages (<a href="apidocs/org/neuclear/id/SignedNamedObject.html">SignedNamedObjects</a> in NeuClear lingo)
--- 27,31 ----
</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)
***************
*** 29,32 ****
--- 34,40 ----
</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-uber.jar from a command line.
We need to have the following ready:
***************
*** 35,45 ****
<li>The Name</li>
<li>A default receiver</li>
! <li>A Public/Private KeyPair</li>
</ul>
<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>
<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
--- 43,55 ----
<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
***************
*** 47,55 ****
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> <![CDATA[
! $ keytool -genkey -keyalg RSA -alias neu://yourdomain.com
Enter keystore password: #####
What is your first and last name?
! [Unknown]: neu://yourdomain.com
What is the name of your organizational unit?
[Unknown]: Your Domain
--- 57,64 ----
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
***************
*** 65,78 ****
[no]: yes
! Enter key password for <neu://yourdomain.com>
! (RETURN if same as keystore password):
! ]]></source>
<p>
! This makes our commandline look like this:
</p>
! <source> <![CDATA[
! java -jar neuclear-id-uber.jar neu://yourdomain.com mailto:joe...@yo...
! ]]></source>
<p>
</p>
</section>
--- 74,201 ----
[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-0.8-SNAPSHOT-uber.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-0.8-SNAPSHOT-uber.jar <b>neu://yourdomain.com mailto:ad...@yo...</b>
! Creating neu://yourdomain.com
! Signing: neu://yourdomain.com
! Saving 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. As the program has to initialise all sorts of cryptographic processes, it might seem a bit slow, but be patient.
! </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>
+ Now lets write a little tiny bit of code to show what we can do:
+ </p>
+ <source>// Lets get hold of your Identity:
+ Identity me=NSResolver.resolveIdentity("<b>neu://yourdomain.com</b>");
+ System.out.println(me.getName());</source>
+ <p>
+ Type this snippet into a main method in some class in your favorite IDE. Add the neuclear jar file you downloaded before to
+ your classpath and run it.
+ If it didnt throw any exceptions you have just resolved your first Identity through the NeuClear ID system.
+ </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-0.8-SNAPSHOT-uber.jar <b>neu://bob@yourdomain.com mailto:bo...@yo...</b>
+ Creating neu://bob@yourdomain.com
+ Signing: neu://bob@yourdomain.com
+ Saving 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>
Index: index.xml
===================================================================
RCS file: /cvsroot/neuclear/neuclear-id/xdocs/index.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -C2 -d -r1.4 -r1.5
*** index.xml 8 Dec 2003 19:32:33 -0000 1.4
--- index.xml 9 Dec 2003 16:42:02 -0000 1.5
***************
*** 17,51 ****
</p>
</section>
! <section name="Rethinking PKI">
! <p>
! I am a big believer in Public/Private Key crypto and digital signatures. The core technology is so elegant and
! has so many uses it is a wonder that it never quite took off. Unless you start
! addressing the many problems involved with the actual implementations and applications of the
! technology, see Ian Griggs wonderful rants here and you might understand:
</p>
!
! <ul><li><a href="http://www.iang.org/ssl/">SSL</a></li>
! <li><a href="http://www.iang.org/ssl/pki_considered_harmful.html">PKI</a></li>
! </ul>
!
! <p>The purpose of writing a new PKI system by scratch for NeuClear was to create a system that was:</p>
!
! <ul><li>Easy to use and understand for average users</li>
! <li>completely legacy free (ie. http (or p2p) not ldap, xml not asn.1 nor x509)</li>
! <li>Not be succeptible to government manipulation such as the dns system.</li>
! <li>Leave CyberSpace <span class="caps">ID</span> to Meat Space <span class="caps">ID</span> mapping to optional higher levels.</li>
! <li>Make accessability a higher priority than theoretical threat analysis (See Ian's rants again above)</li>
! </ul>
<p>
! The NeuClear ID attempts to take flexibility of <a href="http://www.pgp.org">PGP</a> and merge it with the
! ease of use of DNS. We have attempted to stay away from any of the thought processes behind the traditional X509
! CA model as offered by VeriSign, as we belive it doesnt solve any problems and presents too many.
</p>
<p>
! The Core technology is based on XML. With heavy use of the new XML-Signature standard to handle trust and
! security aspects of the framework. The initial implementation is in Java, but there is absolutely no
! reason at all that it couldnt be implemented in say C#, Pythom or Perl.
</p>
! </section>
</body>
--- 17,42 ----
</p>
</section>
! <section name="Busy Developer Guide">
! <p>
! We are working on expanding our documentation now. Besides expanding our <a href="apidocs/index.html">API Documentation</a>,
! we also now have a <a href="bdg.html">busy developers guide</a>. Aimed to get developers started with their own Identities
! quickly and easily.
</p>
! </section>
! <section name="Road Map">
<p>
! The current development version is 0.8-SNAPSHOT. Our aim for 0.8 FINAL is to stabilize and freeze the API.
! Thus the goal is to acheive usability for application developers. This should be reached in mid December 2003.
</p>
<p>
! Our aim for the next version 0.9 is to stabilize and freeze the underlying xml formats and standards as well
! as to create more userland tools. Thus the goal is to fix the underlying format making it easier for other implementations
! of NeuClear ID. This should be reached early on in January 2004
</p>
! <p>
! Our goal is for 1.0 the following release to be fairly polished from a usability standpoint. Our goal is to release this
! in February 2004.
! </p>
! </section>
</body>
Index: installation.xml
===================================================================
RCS file: /cvsroot/neuclear/neuclear-id/xdocs/installation.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** installation.xml 11 Nov 2003 02:31:47 -0000 1.2
--- installation.xml 9 Dec 2003 16:42:02 -0000 1.3
***************
*** 8,12 ****
<body>
! <section name="Requirements">
<p>
To build the NeuClear framework you first need to install <a href="http://maven.apache.org/">Maven</a>.
--- 8,24 ----
<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>
! Download the <a href="http://neuclear.org/maven/neuclear-id/jars/neuclear-id-0.8-SNAPSHOT-uber.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. The jar file also contains all the required libraries and should be suitable for adding to your favorite IDE's classpath.
! </p>
!
! </section>
! <section name="Requirements for Building">
<p>
To build the NeuClear framework you first need to install <a href="http://maven.apache.org/">Maven</a>.
Index: overview.xml
===================================================================
RCS file: /cvsroot/neuclear/neuclear-id/xdocs/overview.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** overview.xml 11 Nov 2003 02:31:47 -0000 1.2
--- overview.xml 9 Dec 2003 16:42:02 -0000 1.3
***************
*** 8,37 ****
<body>
! <section name="Simplifying Identity">
<p>
! If you believe most vendors selling Identity software, Identity is all about identifying the national ID
! number of the person who is clicking the mouse that links to your web site. This means that the relatively
! simple concept of verifying the person who logs in as "misterwhammo" to your web site as the same person
! who buys the t-shirt you are selling is made difficult.
</p>
<p>
! <a href="http://neuclear.org/id/">NeuClear ID</a> aims to cut the <i>Real World</i> aspect of Identity out
! of the core feature of online identity and makes it an optional extra. NeuClear presents Identity as a set
! of simple id's that your average user can easily setup and understand:
</p>
! <ul>
! <li>
! neu://superbux
! </li>
! <li>neu://pelle@super</li>
!
! </ul>
- </section>
- <section name="Hierarchical">
- One of the largest problems with DNS is its Hierarchical nature. However that is also one of its best features.
- It makes it easy to understand. We have taken the hierarchical nature of it and taken away the main problem of
- a central point of failure.
- </section>
</body>
--- 8,43 ----
<body>
! <section name="Rethinking PKI">
! <p>
! I am a big believer in Public/Private Key crypto and digital signatures. The core technology is so elegant and
! has so many uses it is a wonder that it never quite took off. Unless you start
! addressing the many problems involved with the actual implementations and applications of the
! technology, see Ian Griggs wonderful rants here and you might understand:
! </p>
!
! <ul><li><a href="http://www.iang.org/ssl/">SSL</a></li>
! <li><a href="http://www.iang.org/ssl/pki_considered_harmful.html">PKI</a></li>
! </ul>
!
! <p>The purpose of writing a new PKI system by scratch for NeuClear was to create a system that was:</p>
!
! <ul><li>Easy to use and understand for average users</li>
! <li>completely legacy free (ie. http (or p2p) not ldap, xml not asn.1 nor x509)</li>
! <li>Not be succeptible to government manipulation such as the dns system.</li>
! <li>Leave CyberSpace <span class="caps">ID</span> to Meat Space <span class="caps">ID</span> mapping to optional higher levels.</li>
! <li>Make accessability a higher priority than theoretical threat analysis (See Ian's rants again above)</li>
! </ul>
<p>
! The NeuClear ID attempts to take flexibility of <a href="http://www.pgp.org">PGP</a> and merge it with the
! ease of use of DNS. We have attempted to stay away from any of the thought processes behind the traditional X509
! CA model as offered by VeriSign, as we belive it doesnt solve any problems and presents too many.
</p>
<p>
! The Core technology is based on XML. With heavy use of the new XML-Signature standard to handle trust and
! security aspects of the framework. The initial implementation is in Java, but there is absolutely no
! reason at all that it couldnt be implemented in say C#, Pythom or Perl.
</p>
! </section>
</body>
|
