Index of /2007/h6n

Name	Last modified	Size

Parent Directory		-
cookbook.sh	2007-11-23 18:31	272
xmlsec-verify.sh	2007-11-23 18:31	103
Makefile	2007-11-23 22:53	223
h6n.pl	2007-12-06 16:55	24K
README-sig.xml	2007-12-06 16:56	1.3K
README.html	2007-12-06 16:56	7.1K

h6n README

h6n - htmlsign

Author:: Thomas Roessler <tlr@w3.org>
Spec:: http://www.w3.org/2007/11/h6n/
CVS:: http://dev.w3.org/cvsweb/2007/h6n/

Introduction

h6n.pl is a proof of concept implementation of the HTML Signing Profile for XML Signature. The perl script is able to create signatures that conform to the profile, and to verify these signatures.

Known Limitations

The script currently fails if presented with more than one X.509 Certificate, and it does not currently perform Basic Path Validation. I.e., once a signature has been verified, there is no assessment about the trustworthiness of the signature key. Also, rsa-sha1 is the only supported signature algorithm, even though it shouldn't be too difficult to create more flexibility in the future.

Dependencies

h6n.pl depends upon numerous perl modules that are available on CPAN: LWP::UserAgent; Digest::SHA1; XML::LibXML; Crypt::OpenSSL::RSA; Crypt::OpenSSL::X509; Crypt::OpenSSL::Random; MIME::Base64; HTML::Parser; URI.

Usage

Fundamentals

h6n.pl can operate in two distinct modes, sign or verify. There are corresponding command line parameters, "-sign", and "-verify". You'll want to make these the first ones.

All "file name" arguments are in fact URI references. Please use file: URIs for local files.

Signing HTML documents

In order to be able to create signatures with h6n.pl, you need to have a self-signed X.509 certificate and the corresponding private key. The private key must not be protected with a passphrase (this is proof-of-concept code, remember).

If $who is the subject name for the self-signed certificate, then this is a way to create such files with OpenSSL. Note that this is for demonstration only, so we don't bother with even reasonably long keys, or encrypting the signature key.

openssl req -new -sha1 -newkey rsa:512 -rand /dev/urandom \ -subj "$who" -out my.req

openssl x509 -req -in my.req -signkey privkey.pem \ -out cert.pem

openssl rsa -in privkey.pem -out key.pem

cert.pem now contains the self-signed certificate. privkey.pem is the password-protected version of your private key. key.pem is the unencrypted version.

To create a signature, h6n.pl needs at least the following command line parameters:

-sign: indicates that we're in signing mode
-uri uri: indicates what resource we're going to sign
-cert uri: what certificate will be included with the signature?
-priv uri: private signing key
[ -full | -simple ]: what profile to pick -- in the simple profile, only the resource that's being signed is actually hashed; otherwise, a umber of dependent resources are signed as well (e.g., inline images). The simple profile is chosen by default.
[ -add uri ]: Additional resources that are to be included with the signature. Useful when the same content is known under several URIs, and the signature should work for both URIs. Only works with the full profile.

Additionally, h6n.pl is able to deal with multiple variants for one resource. E.g., the W3C logo at http://www.w3.org/Icons/w3c_home can actually be a PNG or a GIF image, depending on content negotiation. To dismabiguate, it is possible to give URIs for multiple representations of a single resource (assuming there are other resources that are actually identical to the various representations):

-rep uri1 uri2: Use uri2 to actually retrieve the resource ientified by uri1. Affects all URI retrieval, include certificates, signature keys, main resource, dependent resource, ...

To deal with content negotiated resources, this parameter can be given multiple times.

Putting it all together, to sign the XML Signature specification, relevant inline images, and both variants of the W3C logo, this will do:

./h6n.pl -sign -full -cert file:cert.pem -priv file:key.pem \ -uri http://www.w3.org/TR/xmldsig-core/ \ -rep http://www.w3.org/Icons/w3c_home http://www.w3.org/Icons/w3c_home.png \ -rep http://www.w3.org/Icons/w3c_home http://www.w3.org/Icons/w3c_home.gif \ > test.xml

Verifying Signatures

In the easiest case, a document that is signed has an appropriate link header that identifies the signature (as this one does). In this case, the invocation is as simple as:

./h6n.pl -verify -uri http://dev.w3.org/2007/h6n/README.html

The script will discover and verify the signature automatically; -uri works the same way as for signing.

Additionally, the following optional command line parameteres work:

-rep uri1 uri2: Use uri2 to actually retrieve the resource ientified by uri1. Affects all URI retrieval, include certificates, signature keys, main resource, dependent resource, ... (In verification mode, only one use per uri1 value makes sense.)
-cert uri: Do not use the certificate embedded with the signature, but instead use the one identified by uri.
-full uri: Do not discover signatures automatically, but instead assume that the resource identified by uri is a signature according to the full profile.
-simple uri: Do not discover signatures automatically, but instead assume that the resource identified by uri is a signature according to the simple profile.