Getting Started

You can either download the JAR which is ready for use but depends on the following (or their equivalents) being present on your classpath:

Alternatively you can checkout the URL Signer source code by issuing

svn export https://urlsigner.svn.sourceforge.net/svnroot/urlsigner

This takes the form of an Ant project with targets as documented by the output of

ant -p

Simply issuing ant without specifying any targets will default to creating the URL Signer JAR but in order to use it you will need to include on your classpath the JARs found in the "lib" directory (or their equivalents.)

Generating a DSA key pair

Whether you download the JAR or the source project you must generate your own public/private DSA key pair. If you have downloaded the JAR then you can generate your DSA key pair using the Java keytool utility by issuing keytool -genkey -dname "CN=URL Signer,OU=urlsigner,O=sourceforge.net,L=Zurich,S=ZH,C=Switzerland" -alias urlsigner -keysize 1024 -keyalg dsa

at which point you will be prompted for keystore and key materials passwords. Note that URL Signer expects an alias of "urlsigner" so if you elect to use a different alias you will need to use the "-a" as described below.

If you have downloaded the sources then you can create an equivalent key pair to the above simply by issuing

ant keys

which creates the necessary Java KeyStore (JKS) container, after being prompted for the passwords, in which the key materials are stored under the "urlsigner" alias.

Using URL Signer to perform signing operations

With your keystore prepared you can sign a URL by issuing the following command replacing "my.key*" values with those that you used when creating your DSA keys

java -cp $URL_SIGNER_CLASSPATH:/path/to/urlsigner.jar net.sourceforge.urlsigner.UrlSigner -k /path/to/keystore -p my.keystore.password -P my.key.materials.password http://urlsigner.sourceforge.net/

where the URL_SIGNER_CLASSPATH variables contains all the JARs found in the "lib" directory. For example on UNIX/Linux bash you might issue:

export URL_SIGNER_CLASSPATH=lib/commons-cli-1.2.jar:lib/commons-codec-1.4.jar

For additional information on using the URL Signer issue the command with the "-h" option. For example if you created your own keystore and used a different alias then you will need to use the "-a" option to override the default "urlsigner" alias.

Using URL Signer in Application Code

Add the URL Signer JAR and its dependencies to your application classpath and place your Keystore file in an appropriate directory. From within your code you can use the SignerUtil type to perform the signing operation as follows:

package foo.bar;
...
import net.sourceforge.urlsigner.keymanager.KeyManager;
import net.sourceforge.urlsigner.keymanager.KeyManagerFactory;
import net.sourceforge.urlsigner.util.SignerUtil
 ...
public class MySignerClass {
...
public void sign(String url, String keyStoreAlias, char[] myKeystorePassword, char[] myKeyPassword) {
...
try {
    KeyManager keyMgr = KeyManagerFactory.getInstance();
    keyMgr.load('/tmp/urlsigner.jks', keyStoreAlias, myKeystorePassword);
    PrivateKey key = keyMgr.getPrivateKey(myKeyPassword);
    String signedUrl = SignerUtil.sign(url, key);
} catch (KeyMaterialsException kme) {
// handle exception ...
} ...
}
...

To verify a signature you should have a running process capable of maintaining the URL Signer signature cache (i.e., should verification be performed by a process that immediately terminates then it will not be capable of detecting replay attacks though it will be able to detect expired signatures.) Typically the verification will occur in a servlet or similar class.

package foo.bar;
...
import net.sourceforge.urlsigner.keymanager.KeyManager;
import net.sourceforge.urlsigner.keymanager.KeyManagerFactory;
import net.sourceforge.urlsigner.util.SignerUtil
 ...
public class MyVerificationClass {
...
private KeyManager keyMgr; ...
// load the keystore once on instantiation
public MyVerificationClass() {
try {
    // default keystore type as cited in $JAVA_HOME/lib/security/java.security is used
    keyMgr = KeyManagerFactory.getInstance();
    keyMgr.load('/tmp/urlsigner.jks', keyStoreAlias, myKeystorePassword);
} catch (KeyMaterialsException kme) {
// handle exception ...
}
}
...
public void verify(String url) {
...
try {
    PublicKey key = keyMgr.getPublicKey();
    boolean isValid = SignerUtil.verify(url, key);
...
} catch (KeyMaterialsException kme) {
// handle exception ...
}
 ...
}
...
}