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 API Specifications can be found in the Project Java Docs.
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.
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).
SignedNamedObjects is the core super class of all business objects within NeuClear. Behind each SignedNamedObject is a XML file with an XML Signature.
The two key pieces of information you would want to get from a SignedNamedObject is who signed it ( Signatory) and it's Digest (Unique Identifier). These can be found with:
An example of loading a signed object from across the internet can be found below:
SignedNamedObject obj=Resolver.resolve("http://talk.org/pelletest.html");
System.out.println("Digest: "+obj.getDigest());
System.out.println("Signatory: "+obj.getSignatory().getName());
Which outputs:
Digest: szt6uy3a2mq7mag27iauj2lrd7cshzuq Signatory: sfjaenowpzytkls4wtqdqhks7k55obbc
The Resolver is a handy class which will attempt to get the object from either a URL or from its local cache.
Any xml following the XML Signature standard for Enveloped Signature with an embedded PublicKey can be used as a Signed Object. NeuClearID offers an easy class Builder to create your own. Builder should generally speaking be subclassed to create objects in your business domain. Here we will use a SignedMessageBuilder to create and sign a simple message.
// First lets create a Signer
BrowsableSigner signer=new DefaultSigner(new SwingAgent());
// Build the unsigned message
SignedMessageBuilder builder=new SignedMessageBuilder("Hello World","How do you do?");
// Sign and convert message
SignedMessage message=(SignedMessage) builder.convert(signer);
This introduces the Signer from NeuClear Commons, which we instantiate to use a Swing GUI front end.
Then we create a builder. The builder is basically a handy way of creating a standardized unsigned XML message.
You then sign and convert the builder using it's convert() method. The method returns a SignedNamedObject which you may cast to a SignedMessage
NeuClear uses the concept of Identity objects. These are simply HTML pages where you can put whatever you want about your self and then sign it. The main object at this is a simple way to give people your public key. These identity pages help provide trust to yourself as well. If you provide a link to a blog from your identity page, people might trust you more than if you were some anonymous no one.
To create an identity object create a html page about yourself. Write as little or as much as you want to. Use a nickname or your real name. You decide. Decide a nickname that people can use to describe you to yourself. Lets say you chose the nickname 'bob'. Pick a piece of html somewhere on your page and add the following:
<div id="nickname">bob</div>
or
<h1 id="nickname">bob</h1>
The key is that an element named nickname exists within the page and that the program can extract your nickname from the document. In future releases we expect to support FOAF vocabulary within your Identity html to support Social Networking and web of trust applications as well.
Targets are where people and services can send you receipts, requests etc. For now you can use your email address. You specify your targets as <link/> elements within the <head/> element of your html:
<html>
<head>
<title>Bob Smith's Identity Page</title>
<link rel="neu:receiver" href="mailto:bob@test.com"/>
</head>
<body>
...
</body>
</html>
Its a good idea to specify as well in this html file the "original source url" which is the URL where this file lives. eg. http://bobsmith.com/bobid.html
<html>
<head>
<title>Bob Smith's Identity Page</title>
<link rel="neu:receiver" href="mailto:bob@test.com"/>
<link rel="original" href=http://bobsmith.com/bobid.html"/>
</head>
<body>
...
</body>
</html>
Once you have created this html file and saved it to disk. Start the NeuClear Personal Signer via Java Web Start to create a new Key Pair ("Personality") and sign the file. Then upload it to the url you put in the original source url link.
We now expand on our previous code to send the signed message to our Identity.
// First lets create a Signer
BrowsableSigner signer=new DefaultSigner(new SwingAgent());
// Build the unsigned message
SignedMessageBuilder builder=new SignedMessageBuilder("Hello World","How do you do?");
// Sign and convert message
SignedMessage message=(SignedMessage) builder.convert(signer);
// Fetch Identity
Identity id=Resolver.resolveIdentity("http://bobsmith.com/bobid.html");
// Send Message
id.send(message);
The resolver has a special version of resolve() called resolveIdentity() which returns an Identity object. Remember the Identity object is a subclass of SignedNamedObject. The Identity object has a method send() which allows you to send messages to the targets of the Identity.