|
From: <pe...@us...> - 2003-12-10 23:58:56
|
Update of /cvsroot/neuclear/neuclear-id/xdocs
In directory sc8-pr-cvs1:/tmp/cvs-serv1921/xdocs
Modified Files:
bdg.xml installation.xml
Log Message:
Did some cleaning up in the builders
Fixed some stuff in IdentityCreator
New maven goal to create executable jarapp
We are close to 0.8 final of ID, 0.11 final of XMLSIG and 0.5 of commons.
Will release shortly.
Index: bdg.xml
===================================================================
RCS file: /cvsroot/neuclear/neuclear-id/xdocs/bdg.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** bdg.xml 9 Dec 2003 23:41:45 -0000 1.3
--- bdg.xml 10 Dec 2003 23:58:52 -0000 1.4
***************
*** 2,12 ****
<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 API">
<h4>Scope</h4>
--- 2,12 ----
<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 API">
<h4>Scope</h4>
***************
*** 22,34 ****
</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>
--- 22,36 ----
</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>
***************
*** 37,43 ****
</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:
! </p>
<ul>
<li>The Name</li>
--- 39,45 ----
</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>
***************
*** 54,64 ****
<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
--- 56,69 ----
<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
***************
*** 75,94 ****
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 --name neu://yourdomain.com --receiver mailto:ad...@yo...
Please enter passphrase for: KeyStore Passphrase for~/.keystore
:
--- 80,104 ----
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
:
***************
*** 99,113 ****
<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>
--- 109,129 ----
<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>
***************
*** 117,121 ****
To verify an Identity type the following in your command prompt:
</p>
! <source>$ java -jar neuclear-id-0.8-SNAPSHOT-uber.jar --verify neu://pelle@neuclear.org
Resolving and Verifying: neu://pelle@neuclear.org
Signed Object: neu://pelle@neuclear.org is verified
--- 133,137 ----
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
***************
*** 140,145 ****
</p>
<ul>
! <li><tt>neu://bob@yourdomain.com</tt></li>
! <li><tt>neu://sales@yourdomain.com</tt></li>
</ul>
<p>
--- 156,165 ----
</p>
<ul>
! <li>
! <tt>neu://bob@yourdomain.com</tt>
! </li>
! <li>
! <tt>neu://sales@yourdomain.com</tt>
! </li>
</ul>
<p>
***************
*** 148,153 ****
</p>
<ul>
! <li><tt>neu://yourdomain.com/store</tt></li>
! <li><tt>neu://yourdomain.com/homebanking</tt></li>
</ul>
<p>
--- 168,177 ----
</p>
<ul>
! <li>
! <tt>neu://yourdomain.com/store</tt>
! </li>
! <li>
! <tt>neu://yourdomain.com/homebanking</tt>
! </li>
</ul>
<p>
***************
*** 156,160 ****
</p>
<p>
! So for our example we picked <tt>neu://bob@yourdomain.com</tt>
</p>
<h4>Creating the Key Pair</h4>
--- 180,185 ----
</p>
<p>
! So for our example we picked
! <tt>neu://bob@yourdomain.com</tt>
</p>
<h4>Creating the Key Pair</h4>
***************
*** 162,169 ****
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
--- 187,196 ----
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
***************
*** 180,192 ****
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 --name neu://bob@yourdomain.com --receiver mailto:bo...@yo...
Please enter passphrase for: KeyStore Passphrase for~/.keystore
:
--- 207,220 ----
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
:
***************
*** 208,212 ****
! </body>
</document>
--- 236,240 ----
! </body>
</document>
Index: installation.xml
===================================================================
RCS file: /cvsroot/neuclear/neuclear-id/xdocs/installation.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -C2 -d -r1.4 -r1.5
*** installation.xml 9 Dec 2003 23:41:45 -0000 1.4
--- installation.xml 10 Dec 2003 23:58:52 -0000 1.5
***************
*** 2,27 ****
<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>
! 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 unpacking and
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>.
Follow their installation instructions and you should be ok. I haven't tried this under windows yet, but I'm guessing
it should work fine. Maven fetches all the required libraries you need the first time you attempt to build it. There are however
--- 2,30 ----
<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>
! Download the
! <a href="http://neuclear.org/maven/neuclear-id/jars/neuclear-id-app-0.8-SNAPSHOT.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 unpacking and
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>.
Follow their installation instructions and you should be ok. I haven't tried this under windows yet, but I'm guessing
it should work fine. Maven fetches all the required libraries you need the first time you attempt to build it. There are however
***************
*** 33,37 ****
</p>
<p>
! If you want to get them yourself. Get the latest version of <a href="http://www.opensymphony.org">OSCore</a> and
<a href="http://www.bouncycastle.org">Bouncy Castle Crypto</a>. For Bouncy Castle Crypto you need a JCE and a provider.
If you're using JDK1.4 you will allready have a JCE. Otherwise the easiest thing todo is to get their combined JCE/Provider.
--- 36,41 ----
</p>
<p>
! If you want to get them yourself. Get the latest version of
! <a href="http://www.opensymphony.org">OSCore</a> and
<a href="http://www.bouncycastle.org">Bouncy Castle Crypto</a>. For Bouncy Castle Crypto you need a JCE and a provider.
If you're using JDK1.4 you will allready have a JCE. Otherwise the easiest thing todo is to get their combined JCE/Provider.
***************
*** 40,44 ****
</p>
<p>
! Remember to edit your <tt>$JAVA_HOME/jre/lib/security/java.security</tt> file as well. Adding the following line:
</p>
<source>
--- 44,49 ----
</p>
<p>
! Remember to edit your
! <tt>$JAVA_HOME/jre/lib/security/java.security</tt> file as well. Adding the following line:
</p>
<source>
***************
*** 47,52 ****
<p>Making sure to change the 6 to whatever the last number is in the sequence of providers</p>
<p>
! In Addition to play around with it you will need a J2EE compliant servlet engine such as <a href="http://jakarta.apache.org/tomcat/">Jakarta Tomcat</a>
! or <a href="http://jetty.mortbay.org">Jetty</a>. Install this as required.
</p>
</section>
--- 52,59 ----
<p>Making sure to change the 6 to whatever the last number is in the sequence of providers</p>
<p>
! In Addition to play around with it you will need a J2EE compliant servlet engine such as
! <a href="http://jakarta.apache.org/tomcat/">Jakarta Tomcat</a>
! or
! <a href="http://jetty.mortbay.org">Jetty</a>. Install this as required.
</p>
</section>
***************
*** 62,67 ****
<source>~/projects/neuclear-id> maven war</source>
<p>
! This should build everything and create a neuclear-id.war file in <tt>target/</tt>. You can then deploy
! this war file in your J2EE compliant servlet engine. eg. place it in tomcat or jetty's <tt>webapps/</tt> directory
and restart.
</p>
--- 69,76 ----
<source>~/projects/neuclear-id> maven war</source>
<p>
! This should build everything and create a neuclear-id.war file in
! <tt>target/</tt>. You can then deploy
! this war file in your J2EE compliant servlet engine. eg. place it in tomcat or jetty's
! <tt>webapps/</tt> directory
and restart.
</p>
|