blautenb 2003/03/14 20:44:03
Added: doc/site forrest-targets.ent forrest.properties status.xml
doc/site/src/documentation README.txt skinconf.xml
doc/site/src/documentation/content/xdocs book-sample.xml
contrib.xml faq.xml history.xml index.xml
license.xml mail-lists.xml site.xml tabs.xml
who.xml xmlsec_entities.ent
doc/site/src/documentation/content/xdocs/Java api.xml
examples.xml faq.xml index.xml installation.xml
interop.xml resolver.xml
doc/site/src/documentation/content/xdocs/c credits.xml
faq.xml index.xml installation.xml interop.xml
programming.xml releases.xml tools.xml
doc/site/src/documentation/resources/images group-logo.gif
icon.png project-logo.gif vc6a.gif vc6b.gif
Log:
Initial checkin of new forrest docs
Revision Changes Path
1.1 xml-security/doc/site/forrest-targets.ent
Index: forrest-targets.ent
===================================================================
<!--
This build.xml snippet contains Forrest targets for Ant 1.5+. It checks that
the user has set ${forrest.home}, either in one of:
build.properties
project.properties
ant.properties
.ant.properties
or with the FORREST_HOME environment variable, and prints an informative error
message if not found.
Usage:
1) Copy this file to somewhere in your project.
2) Add the following to the top of your project's Ant build.xml script
(adjusting the path):
<!DOCTYPE project [
<!ENTITY forrest-targets SYSTEM "file:./forrest-targets.ent">
]>
3) Before the closing '</project>' in your build.xml, add this:
&forrest-targets;
This is like expanding a macro: it pulls in the contents of this file.
A minimal build.xml would thus be:
<!DOCTYPE project [
<!ENTITY forrest-targets SYSTEM "file:./forrest-targets.ent">
]>
<project default="site">
&forrest-targets;
</project>
-->
<target name="site" depends="forrest.init" description="Generates static
HTML documentation">
<ant antfile="${forrest.home}/forrest.antproxy.xml" target="site"/>
</target>
<target name="webapp" depends="forrest.init" description="Generates an
unpackaged webapp of the website">
<ant antfile="${forrest.home}/forrest.antproxy.xml" target="webapp"/>
</target>
<target name="war" depends="forrest.init" description="Generates a .war
file containing the website">
<ant antfile="${forrest.home}/forrest.antproxy.xml" target="war"/>
</target>
<target name="validate" depends="forrest.init" description="Validates XML
documentation files">
<ant antfile="${forrest.home}/forrest.antproxy.xml" target="validate"/>
</target>
<target name="forrest.init" depends="forrest.sethome,
forrest.home.defined"/>
<target name="forrest.sethome" depends="forrest.loadenv,
forrest.checkenv, forrest.checkhome, forrest.check-build.properties,
forrest.check-project.properties, forrest.check-ant.properties,
forrest.check-.ant.properties"/>
<target name="forrest.loadenv" unless="forrest.home.present">
<property environment="env"/>
<echo level="verbose">Forrest: Got ${env.FORREST_HOME}</echo>
</target>
<target name="forrest.checkenv" if="env.FORREST_HOME">
<echo level="verbose">Found $FORREST_HOME..</echo>
<property name="forrest.home" location="${env.FORREST_HOME}"/>
<echo level="verbose">forrest.home set to ${forrest.home}</echo>
<available file="${forrest.home}" type="dir"
property="forrest.home.present"/>
</target>
<target name="forrest.checkhome">
<available file="${forrest.home}" type="dir"
property="forrest.home.present"/>
<available file="build.properties" type="file"
property="build.properties.present"/>
<available file="project.properties" type="file"
property="project.properties.present"/>
<available file="ant.properties" type="file"
property="ant.properties.present"/>
<available file=".ant.properties" type="file"
property=".ant.properties.present"/>
</target>
<!-- No we can't extract the commonalities below into an antcall'ed target,
because it wouldn't be able to set forrest.home -->
<target name="forrest.check-build.properties" unless="forrest.home.present"
if="build.properties.present">
<echo level="verbose">Forrest: Checking build.properties..</echo>
<loadproperties srcfile="build.properties">
<filterchain>
<linecontains>
<contains value="forrest.home"/>
</linecontains>
</filterchain>
</loadproperties>
<available file="${forrest.home}" type="dir"
property="forrest.home.present"/>
</target>
<target name="forrest.check-project.properties"
unless="forrest.home.present"
if="project.properties.present">
<echo level="verbose">Forrest: Checking project.properties..</echo>
<loadproperties srcfile="project.properties">
<filterchain>
<linecontains>
<contains value="forrest.home"/>
</linecontains>
</filterchain>
</loadproperties>
<available file="${forrest.home}" type="dir"
property="forrest.home.present"/>
</target>
<target name="forrest.check-ant.properties" unless="forrest.home.present"
if="ant.properties.present">
<echo level="verbose">Forrest: Checking ant.properties..</echo>
<loadproperties srcfile="ant.properties">
<filterchain>
<linecontains>
<contains value="forrest.home"/>
</linecontains>
</filterchain>
</loadproperties>
<available file="${forrest.home}" type="dir"
property="forrest.home.present"/>
</target>
<target name="forrest.check-.ant.properties" unless="forrest.home.present"
if=".ant.properties.present">
<echo level="verbose">Forrest: Checking .ant.properties..</echo>
<loadproperties srcfile=".ant.properties">
<filterchain>
<linecontains>
<contains value="forrest.home"/>
</linecontains>
</filterchain>
</loadproperties>
<available file="${forrest.home}" type="dir"
property="forrest.home.present"/>
</target>
<target name="forrest.home.defined" depends="forrest.sethome"
unless="forrest.home.present">
<property name="path" value="${user.home}/xml-forrest/build/dist/shbat"/>
<pathconvert targetos="windows" property="winpath">
<path>
<pathelement location="${path}"/>
</path>
</pathconvert>
<pathconvert targetos="unix" property="unixpath">
<path>
<pathelement
location="${path}"/>
</path>
</pathconvert>
<echo>
----------------------------------------------
To run this target, you need Forrest installed.
Please do the following:
export CVSROOT=:pserver:[EMAIL PROTECTED]:/home/cvspublic
cvs checkout xml-forrest
cd xml-forrest
build (Windows)
./build.sh (Unix)
Then either:
- Set FORREST_HOME as the Forrest build instructions describe
- Create a build.properties, with the forrest.home property pointing to
the forrest shbat directory, eg:
forrest.home=${winpath} (Windows)
forrest.home=${unixpath} (Unix)
(adjusting the path according to where your xml-forrest is)
----------------------------------------------
</echo>
<fail message="Need to define $${forrest.home}"/>
</target>
1.1 xml-security/doc/site/forrest.properties
Index: forrest.properties
===================================================================
##############
# Properties used by forrest.build.xml for building the website
##############
# Prints out a summary of Forrest settings for this project
#forrest.echo=true
# Project name (used to name .war file)
#project.name=my-project
# Specifies name of Forrest skin to use
#project.skin=forrest-site
#project.skin=avalon-tigris
#project.skin=krysalis-site
##############
# layout properties
# Properties that must be set to override the default locations
#
# Parent properties must be set. This usually means uncommenting
# project.content-dir if any other property using it is uncommented
#project.status=status.xml
#project.content-dir=src/documentation
#project.conf-dir=${project.content-dir}/conf
#project.sitemap=${project.content-dir}/sitemap.xmap
#project.xdocs-dir=${project.content-dir}/content/xdocs
#project.stylesheets-dir=${project.content-dir}/resources/stylesheets
#project.images-dir=${project.content-dir}/resources/images
#project.schema-dir=${project.content-dir}/resources/schema
#project.skins-dir=${project.content-dir}/skins
#project.skinconf=${project.content-dir}/skinconf.xml
#project.lib-dir=${project.content-dir}/lib
#project.classes-dir=${project.content-dir}/classes
##############
# Cocoon catalog entity resolver properties
# A local catalog to supplement the default Forrest catalog
#project.catalog=${project.schema-dir}/catalog
# The verbosity level for the entity resolver (1..10)
#forrest.catalog.verbosity=1
##############
# validation properties
# These props determine if validation is performed at all
# Values are inherited unless overridden.
# Eg, if forrest.validate=false, then all others are false unless set to true.
#forrest.validate=true
#forrest.validate.xdocs=${forrest.validate}
#forrest.validate.skinconf=${forrest.validate}
#forrest.validate.sitemap=${forrest.validate}
#forrest.validate.stylesheets=${forrest.validate}
#forrest.validate.skins=${forrest.validate}
#forrest.validate.skins.stylesheets=${forrest.validate.skins}
# Key:
# *.failonerror=(true|false) stop when an XML file is invalid
# *.includes=(pattern) Comma-separated list of path patterns to
validate
# *.excludes=(pattern) Comma-separated list of path patterns to not
validate
#forrest.validate.failonerror=true
#forrest.validate.includes=**/*
#forrest.validate.excludes=
#
#forrest.validate.xdocs.failonerror=${forrest.validate.failonerror}
#
#forrest.validate.xdocs.includes=**/*.x*
#forrest.validate.xdocs.excludes=site.xml
#
#forrest.validate.skinconf.includes=${skinconf-file}
#forrest.validate.skinconf.excludes=
#forrest.validate.skinconf.failonerror=${forrest.validate.failonerror}
#
#forrest.validate.sitemap.includes=${sitemap-file}
#forrest.validate.sitemap.excludes=
#forrest.validate.sitemap.failonerror=${forrest.validate.failonerror}
#
#forrest.validate.stylesheets.includes=**/*.xsl
#forrest.validate.stylesheets.excludes=
#forrest.validate.stylesheets.failonerror=${forrest.validate.failonerror}
#
#forrest.validate.skins.includes=**/*
#forrest.validate.skins.excludes=**/*.xsl
#forrest.validate.skins.failonerror=${forrest.validate.failonerror}
#
#forrest.validate.skins.stylesheets.includes=**/*.xsl
#forrest.validate.skins.stylesheets.excludes=
#forrest.validate.skins.stylesheets.failonerror=${forrest.validate.skins.failonerror}
1.1 xml-security/doc/site/status.xml
Index: status.xml
===================================================================
<?xml version="1.0"?>
<status>
<developers>
<person name="Christian Geuer-Pollmann" email="[EMAIL PROTECTED]"
id="CGP" />
<person name="Berin Lautenbach" email="[EMAIL PROTECTED]"
id="BL" />
<person name="Axl Mattheus" email="[EMAIL PROTECTED]" id="AXL"
/>
<person name="Erwin van der Koogh" email="[EMAIL PROTECTED]" id="EK" />
<person name="Karel Wouters" email="[EMAIL PROTECTED]" id="KW"
/>
<!-- Add more people here -->
</developers>
<changes>
<!-- Add new releases here; action attributes: type:(add | fix | update);
-->
<!-- context:(docs | java_something | c_something ) -->
<release version="Java 1.0.5" date="unreleased">
<action dev="KW" type="update" context="docs">
<p>Ported the docs to Forrest</p>
</action>
</release>
<release version="C++ 0.10" date="unreleased">
<action dev="BL" type="add" context="c_rel">
<p>
First release of a Beta for the C++ library.
</p>
</action>
</release>
<release version="Java 1.0.4" date="15 July 2002">
<action dev="CGP" type="update" context="java_jdk">
<p>Java - People who did not install Xalan properly under JDK 1.4.0 now
get a more specific error message.</p>
</action>
<action dev="CGP" type="update" context="java_csp">
<p>Java - We use the most recent version of the BouncyCastle JCE
now.</p>
</action>
</release>
<release version="Java 1.0.3" date="unknown">
<action dev="CGP" type="add" context="java_exc_c14n">
<p>Java - Added support <link href="ext:w3c/c14n"> Exclusive XML
Canonicalization Version 1.0, W3C Recommendation 18 July 2002
</link>. (There is no interop to test vector <link
href="ext:w3c/c14n-interop">Y4</link> because of a problem in Xalan)
</p>
<p>Canonicalization is written completely new: it's about 5-80 times
faster than the implementation in version 1.0.2. It's highly
recommended to upgrade to the new version. </p>
</action>
<action dev="CGP" type="update" context="java_xpath2">
<p>Java - Added support for <link href="ext:w3c/xpath-filterv2">
XML-Signature XPath Filter 2.0, W3C Candidate Recommendation 18
July 2002
</link>
</p>
</action>
</release>
</changes>
<todo>
<actions priority="high">
<action context="Java-code" dev="AXL">
Finish XML Encryption.
</action>
<action context="C++ code" dev="BL">
Create MD5 transform.
</action>
<action context="C++ code" dev="BL">
Create XPath-Filter Transform.
</action>
<action context="C++ code" dev="BL">
Release a "1.00" version.
</action>
<action context="C++ code" dev="BL">
Implement XML Encryption.
</action>
</actions>
<actions priority="medium">
<action context="Java-code" dev="open">
Construct more examples.
</action>
<action context="C++ code" dev="BL">
Build a PGP/GPG signature capability.
</action>
<action context="C++ code" dev="BL">
Implement interface for Windows CAPI.
</action>
</actions>
<actions priority="low">
<action context="docs" dev="KW">
Polish the ported docs. Add more content. Todo and changes are in
<code>status.xml</code>
</action>
<action context="Java-code and C++ code" dev="open">
Implement an XKMS client.
</action>
</actions>
</todo>
</status>
<!-- Keep this comment at the end of the file
Local variables:
mode: xml
sgml-omittag:nil
sgml-shorttag:nil
sgml-namecase-general:nil
sgml-general-insert-case:lower
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-parent-document:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
1.1 xml-security/doc/site/src/documentation/README.txt
Index: README.txt
===================================================================
This is the base documentation directory. It usually contains two files:
skinconf.xml # This file customizes Forrest for your project. In it, you
# tell forrest the project name, logo, copyright info, etc
sitemap.xmap # Optional. This sitemap overrides the default one bundled
# with Forrest. Typically, one would copy a sitemap from
# xml-forrest/src/resources/conf/sitemap.xmap, and customize
# it.
1.1 xml-security/doc/site/src/documentation/skinconf.xml
Index: skinconf.xml
===================================================================
<?xml version="1.0"?>
<!--
Skin configuration file. This file contains details of your project, which
will
be used to configure the chosen Forrest skin.
-->
<!DOCTYPE skinconfig [
<!ENTITY % links.att 'name CDATA #REQUIRED'>
<!ENTITY % link.att 'name CDATA #REQUIRED href CDATA #REQUIRED'>
<!ELEMENT skinconfig (disable-search?, disable-compliance-links?,
searchsite-domain?, searchsite-name?,
project-name, project-url, project-logo, group-name?, group-url?,
group-logo?,
host-url?, host-logo?, year?, vendor?, trail?, credits?)*>
<!ELEMENT credits (credit*)>
<!ELEMENT credit (name, url, image?, width?, height?)>
<!-- id uniquely identifies the tool, and role indicates its function -->
<!ATTLIST credit id CDATA #IMPLIED
role CDATA #IMPLIED>
<!ELEMENT disable-search (#PCDATA)>
<!ELEMENT disable-compliance-links (#PCDATA)>
<!ELEMENT searchsite-domain (#PCDATA)>
<!ELEMENT searchsite-name (#PCDATA)>
<!ELEMENT project-name (#PCDATA)>
<!ELEMENT project-url (#PCDATA)>
<!ELEMENT project-logo (#PCDATA)>
<!ELEMENT group-name (#PCDATA)>
<!ELEMENT group-url (#PCDATA)>
<!ELEMENT group-logo (#PCDATA)>
<!ELEMENT host-url (#PCDATA)>
<!ELEMENT host-logo (#PCDATA)>
<!ELEMENT year (#PCDATA)>
<!ELEMENT vendor (#PCDATA)>
<!ELEMENT trail (link1, link2, link3)>
<!ELEMENT link1 EMPTY>
<!-- Seems we can't use param entity refs until this is DTDified -->
<!ATTLIST link1 name CDATA #REQUIRED href CDATA #IMPLIED>
<!ELEMENT link2 EMPTY>
<!ATTLIST link2 name CDATA #REQUIRED href CDATA #IMPLIED>
<!ELEMENT link3 EMPTY>
<!ATTLIST link3 name CDATA #REQUIRED href CDATA #IMPLIED>
<!ELEMENT name (#PCDATA)>
<!ELEMENT url (#PCDATA)>
<!ELEMENT image (#PCDATA)>
<!ELEMENT width (#PCDATA)>
<!ELEMENT height (#PCDATA)>
]>
<skinconfig>
<!-- Do we want to disable the Google search box? -->
<disable-search>false</disable-search>
<disable-compliance-links>false</disable-compliance-links>
<searchsite-domain>xml.apache.org/security</searchsite-domain>
<searchsite-name>XML Security</searchsite-name>
<!-- mandatory project logo
skin: forrest-site renders it at the top -->
<project-name>Apache XML Security</project-name>
<project-url>http://xml.apache.org/security</project-url>
<project-logo>images/project-logo.gif</project-logo>
<!-- optional group logo
skin: forrest-site renders it at the top-left corner -->
<group-name>Apache XML</group-name>
<group-url>http:///xml.apache.org</group-url>
<group-logo>images/group-logo.gif</group-logo>
<!-- optional host logo (e.g. sourceforge logo)
skin: forrest-site renders it at the bottom-left corner -->
<host-url></host-url>
<host-logo></host-logo>
<!-- The following are used to construct a copyright statement -->
<year>2002</year>
<vendor>The Apache Software Foundation.</vendor>
<!-- Some skins use this to form a 'breadcrumb trail' of links. If you don't
want these, set the attributes to blank. The DTD purposefully requires them.
-->
<trail>
<link1 name="apache" href="http://www.apache.org/"/>
<link2 name="xml.apache" href="http://xml.apache.org/"/>
<link3 name="" href=""/>
</trail>
<!-- Credits are typically rendered as a set of small clickable images in
the
page footer -->
<credits>
<credit>
<name>Built with Apache Forrest</name>
<url>http://xml.apache.org/forrest/</url>
<image>images/built-with-forrest-button.png</image>
<width>88</width>
<height>31</height>
</credit>
<!-- A credit with @role='pdf' will have its name and url displayed in the
PDF page's footer. -->
</credits>
</skinconfig>
1.1
xml-security/doc/site/src/documentation/content/xdocs/book-sample.xml
Index: book-sample.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN"
"book-cocoon-v10.dtd">
<!--
Sample Forrest book.xml file. If renamed to book.xml, this file will
determine
the menu for files in this directory, rather than have a menu be
auto-generated
from site.xml,
NOTE:
If you use site.xml in conjunction with a custom book.xml file, you can use
'site:' URLs in book.xml. Eg, instead of href="sample.html", one could have
href="site:sample".
-->
<book software="MyProj"
title="MyProj"
copyright="@year@ The Apache Software Foundation"
xmlns:xlink="http://www.w3.org/1999/xlink";>
<menu label="About">
<menu-item label="Index" href="index.html"/>
<menu-item label="Sample page" href="sample.html"/>
<menu-item label="Sample ihtml page" href="ihtml-sample.html"/>
<menu-item label="Sample ehtml page" href="ehtml-sample.html"/>
<menu-item label="FAQ" href="faq.html"/>
<menu-item label="Changes" href="changes.html"/>
<menu-item label="Todo" href="todo.html"/>
</menu>
<menu label="Subdir">
<menu-item label="index" href="subdir/index.html"/>
</menu>
</book>
1.1
xml-security/doc/site/src/documentation/content/xdocs/contrib.xml
Index: contrib.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd">
<document>
<header>
<title>Contributing to XML-Security</title>
</header>
<body>
<section>
<title>Introduction</title>
<p>
The XML Security Project is an
<link href="http://www.opensource.org/";>Open Source</link>
volunteer project released
under a very open license. This means there are many ways to contribute
to the
project - either with direct participation (coding, documenting,
answering
questions, proposing ideas, reporting bugs, suggesting bug-fixes,
etc..) or by
resource donations (money, time, publicity, hardware, software,
conference
presentations, speeches, etc...).
</p>
<p>
To begin with, we suggest you to subscribe to the
<link href="site:mail-lists">XML-Security mailing list</link> (follow
the link for
information on how to subscribe and to access the mail list archives).
Listen-in for a while, to hear how others make contributions.
</p>
<p>
You can get your local working copy of the
<link
href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/xml-security";>latest and
greatest code</link> (which you find in the xml-security module in
the CVS code
repository. Review the todo list, choose a task (or perhaps you have
noticed
something that needs patching). Make the changes, do the testing,
generate a
patch, and post to the dev mailing list. (Do not worry - the process is
easy
and explained below.)
</p>
</section>
<section>
<title>Help Wanted Here</title>
<p>
The rest of this document is mainly about contributing new or
improved code and/or documentation, but we would also be glad to have
extra
help in any of the following areas:
</p>
<ul>
<li>
Answering questions on the <code>users</code> mailing list - there
is often a problem of having too many questioners and not enough
experts to
respond to all the questions.
</li>
<li>
Testing the package (especially its less-frequently-used features) on
various configurations and reporting back.
</li>
<li>
Debugging - producing reproduceable test cases and/or finding
causes of bugs. Some known bugs are informally listed on To Do, and
some are
recorded in Bugzilla (see <link href="#procedure">explanation
below</link>).
</li>
<li>
Specifying/analysing/designing new features - and beyond. (If you
wish to get involved with this, please join the mailing list, install
and try out Forrest and read some of the
<link href="site:mail-lists">mail archives</link>. You should have a
strong
"fluency" in XML technologies especially XMLDSig and XML Encryption,
Java or C++ and a basic understanding of the architecture of this
package.
</li>
</ul>
</section> <anchor id="cvshowto"/>
<section>
<title>CVS Usage Precis</title>
<p>
An overview of how to use CVS to participate in the XML Security
development.
Do not be afraid - you cannot accidently destroy the actual code
repository,
because you are working with a local copy as an anonymous user.
Therefore, you
do not have the system permissions to change anything. You can only
update your
local repository and compare your revisions with the real repository.
</p>
<p>
(Further general CVS usage information is at
<link href="http://www.cvshome.org/";>www.cvshome.org</link> and your
local
<code>info cvs</code> pages or <code>man cvs</code> pages or user
documentation.)
</p>
<p>
Have a look at the <link href="site:java/installation">Java</link> or
<link href="site:c/installation">C++</link> installation pages to see
how to get a local copy of the source.
</p>
</section> <anchor id="ssh"/>
<section>
<title>CVS Committer with Secure Shell access</title>
<p>
After a developer has consistently provided contributions (code,
documentation and discussion), then the rest of the dev community may
vote to
grant this developer commit access to CVS.
</p>
<p>
You will need secure access to the repository to be able to commit
patches. Here are some resources that help to get your machine
configured to
use the repository over SSH.
</p>
<ul>
<li><link href="http://cvsbook.red-bean.com/";>The CVS Book</link></li>
<li><link href="http://www.cvshome.org/";>www.cvshome.org</link></li>
<li><link href="https://sourceforge.net/cvs/?group_id=32701";></link> -
See the bottom of the page for links to tips for UNIX and Windows.
Even if you
are on UNIX, the Windows page will also help.</li>
</ul>
</section> <anchor id="procedure"/>
<section>
<title>Procedure for Raising Development Issues</title>
<p>
There are two methods for discussing development and submitting
patches. So that everyone can be productive, it is important to know
which
method is appropriate for a certain situation and how to go about it
without
confusion. This section explains when to use the
<code>developer</code>
<link href="site:mail-lists">mailing list</link> the bug database.
</p>
<p>
Research your topic thoroughly before beginning to discuss a new
development issue. Search and browse through the email archives -
your issue
may have been discussed before. Prepare your post clearly and
concisely.
</p>
<p>
Most issues will be discovered, resolved, and then patched quickly
via the <code>developer</code> mailing list. Larger issues, and ones
that are
not yet fully understood or are hard to solve, are destined for
Bugzilla.
</p>
<p>
Experienced developers use Bugzilla directly, as they are very sure
when they have found a bug and when not. However, less experienced
users should
first discuss it on the user or developer mailing list (as
appropriate).
Impatient people always enter everything into Bugzilla without caring
if it is
a bug of our package or their own installation/configuration mistake
- please do
not do this.
</p>
<p>
As a rule-of-thumb, discuss an issue on the <code>developers</code>
mailing list first to work out any details. After it is confirmed to
be
worthwhile, and you are clear about it, then submit the bug
description or
patch via Bug Tracking.
</p>
<p>
Perhaps you do not get any answer on your first reply, so just post
it again until you get one. (But please not every hour - allow a few
days for
the list to deal with it.) Do not be impatient - remember that the
whole world
is busy, not just you. Bear in mind that other countries will have
holidays at
different times to your country and that they are in different time
zones. You
might also consider rewriting your initial posting - perhaps it was
not clear
enough and the readers eyes glazed over.
</p>
</section> <anchor id="tips"/>
<section>
<title>Contribution Notes and Tips</title>
<p>
This is a collection of tips for contributing to the project in a
manner that is productive for all parties.
</p>
<ul>
<li>
Every contribution is worthwhile. Even if the ensuing discussion
proves it to be off-beam, then it may jog ideas for other people.
</li>
<li>
Use sensible and concise email subject headings. Search engines,
and humans trying to browse a voluminous list, will respond
favourably to a
descriptive title.
</li>
<li>
Start new threads with new Subject for new topics, rather than
reusing the previous Subject line.
</li>
<li>
Keep each topic focused. If some new topic arises then start a new
discussion. This leaves the original topic to continue uncluttered.
</li>
<li>
Whenever you decide to start a new topic, then start with a fresh
new email message window. Do not use the "Reply to"
button, because
threaded mail-readers get confused (they utilise the
<code>In-reply-to</code>
header). If so, then your new topic will get lost in the previous
thread and go
unanswered.
</li>
<li>
Prepend your email subject line with a marker when that is
appropriate, e.g. <code>[Patch]</code>, <code>[Proposal]</code>,
<code>[RT]</code> (Random Thought which quickly blossom into
research topics
:-), <code>[STATUS]</code> (development status of a certain
facility).
</li>
<li>
When making changes to XML documentation, or any XML document for
that matter, use a <link
href="http://www.oasis-open.org/cover/";>validating
parser</link> (one that is tried and true is
<link href="http://openjade.sourceforge.net/";>OpenSP/onsgmls</link>).
This
procedure will detect errors without having to go through the whole
<code>build
docs</code> process to find them. Do not expect Forrest or the
build system to
detect the validation errors for you - they can do it, but that is
not their
purpose. (Anyway, nsgmls validation error messages are more
informative.)
</li>
<li>
Remember that most people are participating in development on a
volunteer basis and in their "spare time". These enthusiasts will
attempt to
respond to issues. It may take a little while to get your answers.
</li>
<li>
Research your topic thoroughly before beginning to discuss a new
development issue. Search and browse through the email archives -
your issue
may have been discussed before. Do not just perceive a problem and
then rush
out with a question - instead, delve.
</li>
<li>
Try to at least offer a partial solution and not just a problem
statement.
</li>
<li>
Take the time to clearly explain your issue and write a concise
email message. Less confusion facilitates fast and complete
resolution.
</li>
<li>
Do not bother to send an email reply that simply says "thanks". When
the issue is resolved, that is the finish - end of thread. Reduce
clutter.
</li>
<li>
You would usually do any development work against the HEAD branch of
CVS.
</li>
<li>
When sending a patch, you usually do not need to worry about which
CVS branch it should be applied to. The maintainers of the repository
will
decide.
</li>
<li>
If an issue starts to get bogged down in list discussion, then it
may be appropriate to go into private off-list discussion with a few
interested
other people. Spare the list from the gory details. Report a summary
back to
the list to finalise the thread.
</li>
<li>
Become familiar with the mailing lists. As you browse and search,
you will see the way other people do things. Follow the leading
examples.
</li>
</ul>
</section>
</body>
</document>
<!-- Keep this comment at the end of the file
Local variables:
mode: xml
sgml-omittag:nil
sgml-shorttag:nil
sgml-namecase-general:nil
sgml-general-insert-case:lower
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-parent-document:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
1.1
xml-security/doc/site/src/documentation/content/xdocs/faq.xml
Index: faq.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE faqs PUBLIC "-//APACHE//DTD FAQ V1.1//EN" "dtd/faq-v11.dtd"
[
<!ENTITY % xmlsec_entities SYSTEM "./xmlsec_entities.ent">
%xmlsec_entities;
]>
<faqs title="Frequently Asked Questions">
<part id="mailinglist">
<title>Mailinglist</title>
<faq id="archive">
<question>
Where's the archive for the list?
</question>
<answer>
<p>
Currently, <link href="ext:gmane">Gmane</link> holds the messages
of the last two weeks. This service also makes the mailinglist
reachable with a news reader.
</p>
<p>
You can use the ezmlm mailing list controller to recieve previous
messages by email. Send an empty email to <link
href="ext:mailhelp">[EMAIL PROTECTED]</link> for detailed
information on how
to use this service
</p>
</answer>
</faq>
<!-- More faqs or parts here -->
</part>
<part id="general">
<title>Required background</title>
<faq id="XML-general">
<question>
Where can I learn about XML?
</question>
<answer>
<p>
There are plenty of resources on the web, just use any search
engine. You might start at <link href="ext:xmlfaq">XMLFAQ</link> or
<link href="ext:zvon">ZVON</link>.
</p>
</answer>
</faq>
<faq id="XMLDSig">
<question>
Where can I learn about XML Digital Signatures?
</question>
<answer>
<p>
The best place to start is <link href="ext:w3c/xmldsig"> &xmldsig;
</link>. Links on XML
security in general can be found on <link
href="ext:christ-page">&christpage; </link>.
</p>
</answer>
</faq>
<faq id="XMLEnc">
<question>
Where can I learn about XML Encryption?
</question>
<answer>
<p>
The best place to start is <link
href="ext:w3c/xmlenc">&xmlenc;</link>. Links on XML
security in general can be found on <link
href="ext:christ-page">&christpage;</link>.
</p>
</answer>
</faq>
<faq id="Crypto">
<question>
Where can I learn about Cryptography in general?
</question>
<answer>
<p>
A lot of resources exist on the web, including the 'green bible' for
cryptography: <link href="ext:hac">&hac;</link>. The &hac; is
completely online and
it should satisfy most of your cryptographic hunger. Disadvantage of
it is that it goes rather deep, so it isn't a executive overview or a
"Learn XYZ in 21 days"-book
</p>
</answer>
</faq>
</part>
<part id="xmldsig">
<title>XMLDSig questions</title>
<faq id="env-transf">
<question>
What is the enveloped transform?
</question>
<answer>
<p>
The enveloped transform is a special transform that enables the use of
so-called enveloped signatures.
</p>
<p>
Enveloped signatures are signatures over an entire XML document, for
which the <code><Signature></code> element is included in the
document itself. An example could be:
</p>
<source>
<![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<Root>
<SomeContent>
...
</SomeContent>]]><em><![CDATA[
<ds:Signature>
<ds:SignedInfo>
<ds:Reference URI="">
<ds:Transforms>
<ds:Transform
Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
</ds:Transforms>
</ds:Reference>
</ds:SignedInfo>
....
</ds:Signature>]]></em><![CDATA[
</Root>]]>
</source>
<p>
The <code>Reference</code> indicates that <code>Root</code> and it's
descendants (except for comments) are signed, but the
<code>Transform</code> element says to throw out the
<code>Signature</code> element (that is the parent of this
<code>Reference</code>) from the stream that is to be signed. Note
that if there are other
<code>Signature</code> elements in <code>Root</code>, they will remain
untouched.
</p>
</answer>
</faq>
<faq id="c14N">
<question>
What's the difference between C14N and ExclC14N?
</question>
<answer>
<p>
C14N was introduced to solve some problems that arise when signing
XML. Because XML allows to change the representation of an XML
document
without changing the actual content, signatures may break when
different parsers are used to generate and verify the signature. A
simple
example of such an allowed change is changing the order of attributes
within an element. (That is solved by C14N by sorting the attributes
by
alphabet)
</p>
<p>
Because a C14N'ed XML fragment inherits all the namespace declarations
from it's ancestors, it is not possible to embed a signed XML fragment
into a document that has other namespace declarations.
</p>
<p>
This is solved by ExclC14N. ExclC14N takes extra information as input
in which you can specify which of the ancestor's namespaces should be
included.
</p>
<p>
For more information on this topic, have a look at the C14N and
ExclC14N sections of the <jump href="site:w3c/xmldsig">W3C XMLDSig
WG</jump>.
</p>
</answer>
</faq>
<!-- template
<faq id="">
<question>
</question>
<answer>
</answer>
</faq>
-->
</part>
<!-- More faqs or parts here -->
</faqs>
1.1
xml-security/doc/site/src/documentation/content/xdocs/history.xml
Index: history.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd"
[
<!ENTITY % xmlsec_entities SYSTEM "./xmlsec_entities.ent">
%xmlsec_entities;
]>
<document>
<header>
<title>XML Security History</title>
</header>
<body>
<section>
<title>The <WebSig> project</title>
<p>
In mid-1999, the <jump
href="http://www.nue.et-inf.uni-siegen.de/";>Institute for Data
Communications Systems</jump> at the <jump
href="http://www.uni-siegen.de/";>University of Siegen</jump> in
Germany looked for partners to participate in a European project for
implementing the upcoming <jump href="ext:w3c/xmldsig">XML Signature
standard</jump>. We found our partners in the companies <jump
href="http://www.expnet.gr/";>Expertnet S.A.</jump> and <jump
href="http://www.proodos.gr/";>PROODOS S.A.</jump>, both from Athens,
who were willing to use our XML Signature library in a first commercial
project.
</p>
<p>
The project started in January 2000 and ended up in September 2001. 50%
of the costs have been funded by the European Commission in the <jump
href="http://www.ispo.cec.be/isis/99websig.htm";>ISIS
programme</jump>. Goal was to develop a JAVA library for creating and
validating XML Signatures and to make the binaries of this software
freely available.
</p>
<p>In September 2001, the Institute for Data Communications Systems
decided to
make the sources freely available, too, to promote the use of digital
signatures and to give XML Signature a spin. The decision was made to
give the complete library (including an implementation of "Canonical
XML" and "XML Signature") under the hood of the Apache Software
Foundation to ensure availablility of the source and to enable other
people to use it under the Apache License.
</p>
</section>
<section>
<title>XML Encryption</title>
<p>2Bdone</p>
</section>
<section>
<title>The C++ Library</title>
<p>The C++ library is a much more recent addition to the XML-Security
project. It started out on <jump href="http://www.sourceforge.net";>
Sourceforge</jump> and was migrated into XML Security in early 2003.
</p>
</section>
</body>
</document>
<!-- Keep this comment at the end of the file
Local variables:
mode: xml
sgml-omittag:nil
sgml-shorttag:nil
sgml-namecase-general:nil
sgml-general-insert-case:lower
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-parent-document:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
1.1
xml-security/doc/site/src/documentation/content/xdocs/index.xml
Index: index.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd">
<document>
<header>
<title>Welcome to XML Security</title>
</header>
<body>
<section>
<title>News</title>
<p>
The site has now been re-built using the new xml.apache.org standard,
using Forrest.
</p>
</section>
<section>
<title>The Project</title>
<p>
The XML Security project is aimed at providing implementation of
security standards for XML. Currently the focus is on the W3C
standards :
</p>
<ul>
<li><jump href="http://www.w3.org/Signature/";>
XML-Signature Syntax and Processing; and</jump>
</li>
<li><jump href="http://www.w3.org/Encryption/2001/";>
XML Encryption Syntax and Processing.</jump></li>
</ul>
<p>
Once these are implemented,
<jump href="http://www.w3.org/2001/XKMS";>XML Key Management</jump>
is likely to be the next focus for the project.
</p>
<p>
Two libraries are currently available.
</p>
<ol>
<li>A Java library, which includes a mature Digital Signature
implementation. Encryption is currently under development.</li>
<li>A C++ library is also now available. Currently this is in
beta and supports Digital Signature processing only.</li>
</ol>
</section>
</body>
</document>
1.1
xml-security/doc/site/src/documentation/content/xdocs/license.xml
Index: license.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd">
<document>
<header>
<title>The Apache Software License, Version 1.1</title>
</header>
<body>
<source><![CDATA[
Copyright (C) 2002 The Apache Software Foundation. All rights reserved.
Redistribution and use in source and binary forms, with or without modifica-
tion, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
3. The end-user documentation included with the redistribution, if any, must
include the following acknowledgment: "This product includes software
developed by the Apache Software Foundation (http://www.apache.org/)."
Alternately, this acknowledgment may appear in the software itself, if
and wherever such third-party acknowledgments normally appear.
4. The names "Apache Forrest" and "Apache Software Foundation" must not be
used to endorse or promote products derived from this software without
prior written permission. For written permission, please contact
[EMAIL PROTECTED]
5. Products derived from this software may not be called "Apache", nor may
"Apache" appear in their name, without prior written permission of the
Apache Software Foundation.
THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
APACHE SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLU-
DING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
This software consists of voluntary contributions made by many individuals
on behalf of the Apache Software Foundation. For more information on the
Apache Software Foundation, please see <http://www.apache.org/>.]]></source>
</body>
</document>
1.1
xml-security/doc/site/src/documentation/content/xdocs/mail-lists.xml
Index: mail-lists.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd">
<document>
<header>
<title>XML security mailing list</title>
</header>
<body>
<section>
<title>XML security mailing list</title>
<p>
There exists a mailing list which you can subscribe to ask questions:
</p>
<p>
The <jump href="ext:xml.apache.org/mail">ezmlm mailing list
controller</jump>
accepts commands by sending emails to it, generally
like the following:
</p>
<ul>
<li>
<jump href="ext:mailsub">security-dev-subscribe</jump> to subscribe
your current email address to the list.
</li>
<li>
<jump href="ext:mailunsub">security-dev-unsubscribe</jump> to
<em>un</em>subscribe your *current* email address from the list.
</li>
<li>
<jump href="ext:mailhelp">security-dev-help</jump> to get Help on
mailing list commands.
</li>
</ul>
</section>
<section>
<title>Mail Archives</title>
<p>
An archive of this list is kept under
<jump href="ext:gmane">
http://news.gmane.org/thread.php?group=gmane.text.xml.security.devel
</jump>
</p>
<p>
Another archive is held by <jump href="ext:nagoya">The EyeBrowse Mail
Archive
</jump>.
</p>
</section>
</body>
</document>
1.1
xml-security/doc/site/src/documentation/content/xdocs/site.xml
Index: site.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE site
[
<!ENTITY % xmlsec_entities SYSTEM "xmlsec_entities.ent">
%xmlsec_entities;
]>
<site label="XML Security" href=""
xmlns="http://apache.org/forrest/linkmap/1.0";>
<about label="About">
<index label="Index" href="index.html"/>
<!-- <download label="Download"
href="http://xml.apache.org/security/dist/"/> -->
<download label="Download"
href="http://www.apache.org/dyn/closer.cgi/xml/security/"/>
<faq label="FAQs" href="faq.html"/>
<who label="Who we are" href="who.html"/>
<todo label="Todo" href="todo.html"/>
<changes label="Changes" href="changes.html"/>
<history label="History" href="history.html"/>
<license label="License" href="license.html"/>
</about>
<getting-involved label="Getting Involved">
<contrib label="Contributing" href="contrib.html"/>
<CVS label="CVS" href="http://cvs.apache.org/viewcvs/xml-security/"/>
<mail-lists label="Mail lists" href="mail-lists.html"/>
</getting-involved>
<java label="Java" href="Java/">
<!-- changes label="Changes" href="changes.html"/ -->
<index label="Index" href="index.html"/>
<installation label="Installation" href="installation.html" />
<examples label="Examples" href="examples.html"/>
<faq_j label="FAQs" href="faq.html"/>
<api label="API Docs" href="api.html" />
<interop label="Interoperability" href="interop.html"/>
<gump label="Gump results"
href="http://cvs.apache.org/builds/gump/latest/xml-security.html"; />
<resolvers label="Resolvermania" href="resolver.html"/>
</java>
<c label="C++" href="c/">
<index label="Index" href="index.html"/>
<install label="Installation" href="installation.html"/>
<programming label="Programming" href="programming.html"/>
<cfaq label="FAQs" href="faq.html"/>
<external label="API Docs" href="apiDocs/index.html"/>
<tools label="Tools" href="tools.html"/>
<releases label="Release Information" href="releases.html"/>
<credits label="Credits" href="credits.html"/>
<interop label="Interoperability" href="interop.html"/>
</c>
<references label="References">
<xmldsig label="W3C XML DSig" href="http://www.w3c.org/Signature"/>
<xmlenc label="W3C XML Enc" href="http://www.w3c.org/Encryption"/>
</references>
<external-refs>
<!-- NOTE: the label atts are not defined/used in Forrest; I added them
for -->
<!-- later use. Karel. -->
<!-- Christian's security page -->
<christ-page label="The XML Security page"
href="http://www.nue.et-inf.uni-siegen.de/~geuer-pollmann/xml_security.html"/>
<!-- W3C -->
<w3c href="http://www.w3c.org/";>
<xmldsig label="&xmldsig;" href="Signature"/>
<xmldsig_java_supported label="&supp_java_dsig;"
href="&supp_java_dsig_ref;"/>
<xmldsig_C_supported label="&supp_C_dsig;" href="&supp_C_dsig_ref;"/>
<xmlenc_java_supported label="&supp_java_enc;"
href="&supp_java_enc_ref;"/>
<xmlenc_C_supported label="&supp_C_enc;" href="&supp_C_enc_ref;"/>
<xmlenc label="&xmlenc;" href="Encryption"/>
<c14n label="C14N-supported" href="TR/2002/REC-xml-exc-c14n-20020718/"
/>
<c14n-interop label="C14N tests"
href="Signature/2002/02/01-exc-c14n-interop.html" />
<xpath-filterv2 label="XMLDSig XPath Filter 2.0"
href="TR/2002/CR-xmldsig-filter2-20020718/" />
<xpath label="XML Path Language (XPath) Version 1.0" href="TR/xpath"/>
<dom label="DOM" href="DOM"/>
<dom2 label="DOM level 2" href="DOM-Level-2/"/>
</w3c>
<!-- SAX -->
<sax label="SAX" href="http://www.megginson.com/SAX/sax.html"/>
<sax2 label="SAX 2" href="http://www.megginson.com/SAX/Java/index.html"/>
<!-- Apache -->
<xml.apache.org href="http://xml.apache.org/";>
<xml4j-used label="Apache Xerces2" href="xerces2-j/index.html"/>
<ApacheLicense label="The Apache Software License, Version 1.1"
href="dist/LICENSE.txt"/>
<forrest href="forrest/"/>
<mail href="mail.html"/>
</xml.apache.org>
<ant label="Ant" href="http://jakarta.apache.org/ant/index.html"/>
<bugzilla label="Bugzilla (the Apache bug database)"
href="http://nagoya.apache.org/bugzilla"/>
<buglist label="XalanJ2 open bugs"
href="http://nagoya.apache.org/bugzilla/buglist.cgi?bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&email1=&emailtype1=substring&emailassigned_to1=1&email2=&emailtype2=substring&emailreporter2=1&bugidtype=include&bug_id=&changedin=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&product=XalanJ2&short_desc=&short_desc_type=substring&long_desc=&long_desc_type=substring&bug_file_loc=&bug_file_loc_type=substring&keywords=&keywords_type=anywords&field0-0-0=noop&type0-0-0=noop&value0-0-0=&cmdtype=doit&order=%27Importance%27"/>
<!-- Java -->
<java>
<docs>
<full-api href=""/>
<hierachry href=""/>
<gumpdocs
href="http://nagoya.apache.org/gump/javadoc/xml-security/build/doc/html/api/index.html";
/>
</docs>
<jce>
<download href="http://www.bouncycastle.org/download/";>
<file href="&jce_download_file;"/>
</download>
</jce>
</java>
<!-- Crypto and CSPs -->
<hac label="&hac;" href="http://www.cacr.math.uwaterloo.ca/hac/"/>
<bouncy label="Boucy Castle" href="http://www.bouncycastle.org/"/>
<!-- SUN -->
<java label="Java (TM) 2 Platform Standard Edition v1.4.0"
href="http://java.sun.com/j2se/1.4/index.html"/>
<javaforum label="SUN java forum" href="http://forum.java.sun.com/"/>
<jaxp label="Java API for XML Parsing 1.0"
href="http://java.sun.com/xml/docs/api/index.html"/>
<!-- General information -->
<zvon label="ZVON" href="http://www.zvon.org/"/>
<xmlfaq label="XMLFAQ" href="http://www.ucc.ie/xml/"/>
<bsf label="Bean Scripting Framework (BSF)"
href="http://oss.software.ibm.com/developerworks/projects/bsf"/>
<!-- Mailing list -->
<nagoya label="EyeBrowseList"
href="http://nagoya.apache.org/eyebrowse/SummarizeList?listId=72"/>
<gmane label="Gmane"
href="http://news.gmane.org/thread.php?group=gmane.text.xml.security.devel"/>
<mailhelp label="mailinglisthelp" href="mailto:[EMAIL PROTECTED]"/>
<mailsub label="mailinglistsubscribe" href="mailto:[EMAIL PROTECTED]"/>
<mailunsub label="mailinglistunsubscribe" href="mailto:[EMAIL
PROTECTED]"/>
<!-- Contacts (this should change in a future version of Forrest) -->
<geuerp label="Christian Geuer-Pollmann" href="mailto:[EMAIL PROTECTED]"/>
<!-- Links to specific emails -->
<mail>
<linkmaps
href="http://marc.theaimsgroup.com/?l=forrest-dev&m=103444028129281&w=2"/>
<semantic-linking
href="http://marc.theaimsgroup.com/?l=forrest-dev&m=103097808318773&w=2"/>
<inputmoduletransformer
href="http://marc.theaimsgroup.com/?t=103992708800001&r=1&w=2"/>
<linkrewritertransformer
href="http://nagoya.apache.org/bugzilla/show_bug.cgi?id=15611"/>
<xpathtransformer
href="http://nagoya.apache.org/bugzilla/show_bug.cgi?id=12235"/>
</mail>
</external-refs>
</site>
<!-- Keep this comment at the end of the file
Local variables:
mode: xml
sgml-omittag:nil
sgml-shorttag:nil
sgml-namecase-general:nil
sgml-general-insert-case:lower
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-parent-document:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
1.1
xml-security/doc/site/src/documentation/content/xdocs/tabs.xml
Index: tabs.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE tabs PUBLIC "-//APACHE//DTD Cocoon Documentation Tab V1.0//EN"
"tab-cocoon-v10.dtd">
<tabs software="XML Security"
title="Apache XML Security"
copyright="@year@ The Apache Foundation"
xmlns:xlink="http://www.w3.org/1999/xlink";>
<!-- The rules are:
@dir will always have /index.html added.
@href is not modified unless it is root-relative and obviously specifies a
directory (ends in '/'), in which case /index.html will be added
-->
<tab label="Home" dir=""/>
<tab label="Java" dir="Java"/>
<tab label="C++" dir="c"/>
</tabs>
1.1
xml-security/doc/site/src/documentation/content/xdocs/who.xml
Index: who.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd">
<document>
<header>
<title>Who we are</title>
</header>
<body>
<section>
<title>The Apache XML-Security Community</title>
<p> The XML-Security Project operates on a meritocracy: the more you
do, the
more responsibility you will obtain. This page lists all of the
people who have
gone the extra mile and are Committers. If you would like to get
involved, the
first step is to join the mailing lists. </p>
<p> We ask that you please do not send us emails privately asking for
support. We are non-paid volunteers who help out with the project and
we do not
necessarily have the time or energy to help people on an individual
basis.
Instead, we have set up mailing lists which often contain hundreds of
individuals who will help answer detailed requests for help. The
benefit of
using mailing lists over private communication is that it is a shared
resource
where others can also learn from common mistakes and as a community
we all grow
together.</p>
</section>
<section>
<title>Committers</title>
<ul>
<li> [CGP] Christian Geuer-Pollmann
(geuer-pollmannATnue.et-inf.uni-siegen.de) </li>
<li> [BL] Berin Lautenbach (berinATozemail.com.au) </li>
<li> [AXL] Axl Mattheus (axl.mattheusATsun.com) </li>
<li> [EK] Erwin van der Koogh (erwinATkoogh.com) </li>
</ul>
</section>
</body>
</document>
<!-- Keep this comment at the end of the file
Local variables:
mode: xml
sgml-omittag:nil
sgml-shorttag:nil
sgml-namecase-general:nil
sgml-general-insert-case:lower
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-parent-document:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
1.1
xml-security/doc/site/src/documentation/content/xdocs/xmlsec_entities.ent
Index: xmlsec_entities.ent
===================================================================
<!ENTITY packagenamelong "Apache-XML-Security-J">
<!ENTITY packagename "xml-security">
<!ENTITY packageversion "1.0.5D2">
<!ENTITY packagedirectory "NOT USED ??">
<!ENTITY packagedistname "Apache-XML-Security-J">
<!ENTITY jce_download_file "jce-jdk13-114.jar">
<!ENTITY lib_jce "./libs/bc-&jce_download_file;">
<!-- ENTITY packagenamelong "@@packagenamelong@@"-->
<!-- ENTITY packagename "@@packagename@@"-->
<!-- ENTITY packageversion "@@packageversion@@"-->
<!-- ENTITY packagedirectory "@@packagedirectory@@ "-->
<!-- ENTITY packagedistname "@@packagedistname@@ Apache-XML-Security-J"-->
<!ENTITY xmlsec "Apache-XML-Security-J">
<!ENTITY xmldsig "W3C XML-Signature Syntax and Processing">
<!ENTITY xmlenc "W3C XML Encryption Syntax and Processing">
<!ENTITY hac "Handbook of Applied Cryptography">
<!ENTITY christpage "The XML Security Page">
<!ENTITY supp_java_dsig "XML-Signature Syntax and Processing, W3C
Recommendation 12 February 2002">
<!ENTITY supp_java_dsig_ref "TR/2002/REC-xmldsig-core-20020212/">
<!ENTITY supp_C_dsig "XML-Signature Syntax and Processing, W3C
Recommendation 12 February 2002">
<!ENTITY supp_C_dsig_ref "TR/2002/REC-xmldsig-core-20020212/">
<!ENTITY supp_java_enc "XML Encryption Syntax and Processing, W3C
Recommendation 10 December 2002">
<!ENTITY supp_java_enc_ref "TR/2002/REC-xmlenc-core-20021210/">
<!ENTITY supp_C_enc "XML Encryption Syntax and Processing, W3C Recommendation
10 December 2002">
<!ENTITY supp_C_enc_ref "TR/2002/REC-xmlenc-core-20021210/">
<!ENTITY api_ref "api/org/apache/xml/security/">
1.1
xml-security/doc/site/src/documentation/content/xdocs/Java/api.xml
Index: api.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd"
[
<!ENTITY % xmlsec_entities SYSTEM "../xmlsec_entities.ent">
%xmlsec_entities;
]>
<document>
<header>
<title>Java API Documentation</title>
</header>
<body>
<section>
<title>Javadoc Generated Documentation</title>
<p>&packagenamelong; comes packaged with API documentation.</p>
<p>This documentation is generated automatically from the Javadoc-style
comments inside the source files. Click on one of the links below to
go to the appropriate API documentation.</p>
</section>
<section>
<title>&packagename; API Documentation</title>
<ul>
<li><jump href="ext:java/docs/full-api">Full API
documentation</jump></li>
<li><jump href="ext:java/docs/hierachry">Hierarchy for all the
packages</jump></li>
<li>If the above documentation is outdated, an always-fresh copy can be
found <jump href="ext:java/docs/gumpdocs">here</jump></li>
</ul>
</section>
</body>
</document>
1.1
xml-security/doc/site/src/documentation/content/xdocs/Java/examples.xml
Index: examples.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd"
[
<!ENTITY % xmlsec_entities SYSTEM "../xmlsec_entities.ent">
%xmlsec_entities;
]>
<document>
<header>
<title>Java Examples</title>
</header>
<body>
<section>
<title>About</title>
<p>
Part of this software can be used to create and verify arbitrary forms
of XML Signatures. The documentation available here is not very huge;
my first approach is to supply usage examples which are available in
the <code>src_samples/</code> directory to give interested users a
first starting point to jump-start with XML Signature.
</p>
<note>
The samples divide into two groups: Samples that <em>create</em> and
samples that <em>verify</em> Signatures. Eventually, you should adjust
the verifying program to another filename if you get
<code>FileNotFoundException</code>s.
</note>
<fixme author="KW">
We should add more information here.
</fixme>
</section>
</body>
</document>
1.1
xml-security/doc/site/src/documentation/content/xdocs/Java/faq.xml
Index: faq.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE faqs PUBLIC "-//APACHE//DTD FAQ V1.1//EN" "dtd/faq-v11.dtd"
[
<!ENTITY % xmlsec_entities SYSTEM "../xmlsec_entities.ent">
%xmlsec_entities;
]>
<faqs title="Frequently Asked Questions - Java">
<part id="general_j">
<title>Questions about Java</title>
<faq id="security_j">
<question>
I have a Java-(security/cryptography) problem. Can you help me?
</question>
<answer>
<p>
Go to the <link href="ext:javaforum">java forum</link> of Sun. You can
find forums where you can ask questions like "How do I generate
a keypair", etc.
</p>
</answer>
</faq>
<faq id="xml_j">
<question>
I have a Java-XML problem.
</question>
<answer>
<p>
Go to the <link href="ext:javaforum">java forum</link> of Sun, section
Java Technology & XML and have a look at <link
href="ext:xml.apache.org/xml4j-used"> Apache Xerces</link>.
</p>
</answer>
</faq>
</part>
<part id="specific_">
<title>Questions about this package</title>
<faq id="crimson">
<question>
I'm using Crimson, but it throws Exceptions. Why?
</question>
<answer>
<p>
Crimson is not supported at the moment. The main reason is that
Crimson did not support the
<code>org.w3c.dom.traversal.TreeWalker</code> interface in the
past. Additionally, it does not support the
<code>org.apache.xerces.dom.DocumentImpl.putIdentifier(String ID,
Element e)</code> functionality where Xerces allows us to enable ID
attributes during document generation.
</p>
<p>
Use <link href="ext:xml.apache.org/xml4j-used">Apache Xerces</link>
instead of Crimson.
</p>
</answer>
</faq>
<faq id="bouncy">
<question>
What's up with the Bouncy Castle CSP? / Where is my CSP?
</question>
<answer>
<p>
There is <em>no</em> JCE bundled together with this
distribution. This is because the Apache Project web site is hosted
in the US where some export restrictions apply to the cryptographic
primitives.
</p>
<p>
The nice guys from the <jump href="ext:bouncy">Legion of Bouncy
Castle</jump> where so helpful to supply their JCE in a simple JAR
package so that we can simply fetch it during the compilation process
and put it into the <code>libs/</code> directory. When you use the
ant makefile <code>build.xml</code> and simply say <code>ant
compile</code> or <code>ant get-jce</code>, <code>ant</code> tries
to fetch this JAR from the australian server. After that step, the
compilation works completely.
</p>
<p>
The ant make tools initiates an automated download of the
BouncyCastle JCE. The file is downloaded into the <code>libs/</code>
directory and a "bc-" is prepended to the filename. This is
done because we want the provider name (bc means BouncyCastle) being
visible in the JAR's filename.
</p>
<note>
The fact that we <em>use</em> Bouncy in this project does not mean
that you <em>must</em> use it, it's only the default. If you take a
look at the configuration
<code>src/org/apache/xml/security/resource/config.xml</code>, you'll
notice the sections which do integrate these alternative JCEs.
</note>
<p>
More information can be found in the <link
href="site:java/installation">Installation</link> section.
</p>
</answer>
</faq>
<faq id="logging">
<question>
How do I enable/turn off logging?
</question>
<answer>
<p>
The logging is configured in the <code>config.xml</code> file which
either in the <code>xmlsec.jar</code> file or in the class path. This
is a little bit complicated as config.xml is used both for library
wide configurations like algorithms as well as for the user setting
about log4j. This will be changed someday ;-))
</p>
<p>OK, so it goes: In the
<jump
href="http://cvs.apache.org/viewcvs.cgi/xml-security/src/org/apache/xml/security/resource/config.xml?rev=HEAD&content-type=text/vnd.viewcvs-markup";>
<code>xml-security/src/org/apache/xml/security/resource/config.xml</code>
</jump> file, there is an element called
<code><log4j:configuration></code>. This element contains the
XML style configuration information as defined in the
<jump
href="http://jakarta.apache.org/log4j/docs/api/org/apache/log4j/xml/DOMConfigurator.html";>
log4j DOMConfigurator class
</jump>. You can find examples
<jump
href="http://cvs.apache.org/viewcvs.cgi/jakarta-log4j/tests/input/xml/";>here</jump>
</p>
</answer>
</faq>
<faq id="baseURI">
<question>
What is the meaning of <code>BaseURI</code>?
</question>
<answer>
<p>
When you work with URIs like
"<code>http://www.example.com/index.html</code>", it is
quite sure what you mean as this is an absolute URL, i.e. it is clear
which protocol ise used to fetch which file from which server. When
you use such a URL inside a signature, the software can automatically
figure out what you sign. But when you sign something in your local
file system or if you use a relative path like
"<code>../1.txt</code>", it's not possible to understand
this reference without some context. <em>This</em> context is the
<code>BaseURI</code>. For instance, if you sign
<code>URI="../1.txt"</code> and the
<code>BaseURI="file:///home/user/work/signature.xml"</code>,
it is clear that the file
<code>BaseURI="file:///home/user/1.txt"</code> is to be
signed. But when you create the signature, the file
<code>BaseURI="file:///home/user/work/signature.xml"</code>
does not yet exist; therefore, you have to supply the URL where you
intend to store the signature later (relative to the signed objects).
</p>
<p>
The String BaseURI is the systemID on which the Object will be stored
in the future. This is needed to resolve relative links in the
<code>Reference</code> elements which point to the filesystem or
something similar.
</p>
<p>
Example: Imagine that you want to create a signature to store it on a
web server as
<code>http://www.acme.com/signatures/sig1.xml</code>. So
<code>BaseURI="http://www.acme.com/sig1.xml"</code>. This
means that if you create a <code>Reference</code> with
<code>URI="./index.html"</code>, the library can easily use
it's HTTPResourceResolver to fetch
<code>http://www.acme.com/index.html</code> without that you have to
say <code>URI="http://www.acme.com/index.html"</code>.
</p>
</answer>
</faq>
<faq id="examples">
<question>
How do I use the package to generate and verify a signature?
</question>
<answer>
<p>
Checkout the samples in
<code>src_samples/org/apache/xml/security/samples/signature/</code>.
</p>
<note>
The samples divide into two groups: Samples that <em>create</em> and
samples that <em>verify</em> Signatures. Eventually, you should
adjust the verifying program to another filename if you get
<code>FileNotFoundException</code>s.
</note>
</answer>
</faq>
<faq id="jdk140">
<question>
I'm using SUN JDK v1.4.0 or v1.4.1 and it get some exceptions. Any
clues?
</question>
<answer>
<p>
After SUN released the <jump href="ext:java"> Java (TM) 2 Platform
Standard Edition v1.4.0 </jump>, the xml-security package stopped
working. This is a
<jump
href="http://developer.java.sun.com/developer/bugParade/bugs/4615582.html";>
known
</jump>
problem: SUN packaged a beta of Xalan into the JDK1.4.0, but the
xml-security package requires a stable version of Xalan (v2.2.0 or
later). To fix the problem, you have to put the xalan.jar into a
special directory in your JDK:
<code>j2sdk1.4.0/jre/lib/endorsed/xalan.jar</code>. If you installed
an out-of-the-box JDK1.4 (e.g. on Windows 2000), the
"endorsed" directory does not exist: you'll have to create
it by hand.
</p>
<warning>Putting this JAR to another location like lib/ext WILL NOT
WORK. </warning>
<p>
For more on that, you can also check the <jump
href="http://xml.apache.org/~edwingo/jaxp-faq.html#override";>
Unofficial JAXP FAQ </jump>.
</p>
</answer>
</faq>
<faq id="nullptrexception">
<question>
I get a NullPointerException, and I don't know what's wrong.
</question>
<answer>
<p>
Often, this problem is caused by using DOM1 calls like
<code>createElement(), setAttribute(), createAttribute()</code>.
These are
non-namespace-aware and will cause XPath and C14N errors.
Always use the DOM2 <code>create(Attribute|Element)NS(...)</code>
methods instead, even if you're creating an element without a
namespace
(in that case, you can use null as a namespace).
</p>
<p>
The Xalan-J Team told us that DOM1 calls are deprecated and are not to
be used in code. xml-security has been reviewed and is DOM1 clean
now.
The Xalan folks told us that if you create Elements or attributes
using DOM1 calls which are not namespace aware, they do not care about
any problem you have because of incorrect hehaviour of Xalan.
</p>
</answer>
</faq>
</part>
</faqs>
1.1
xml-security/doc/site/src/documentation/content/xdocs/Java/index.xml
Index: index.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd"
[
<!ENTITY % xmlsec_entities SYSTEM "../xmlsec_entities.ent">
%xmlsec_entities;
]>
<document>
<header>
<title>The Java section</title>
</header>
<body>
<section>
<title>News</title>
<p>Version 1.0.4 released on 15 July 2002; minor
improvements. The most significant is that people who did not install
Xalan properly under JDK 1.4.0 get a more specific error message. It
uses the most recent version of the BouncyCastle JCE now. </p>
</section>
<section>
<title>XML Security Release</title>
<p>
The &packagenamelong; &packageversion; supports
<jump href="ext:w3c/xmldsig_java_supported">&supp_java_dsig;
</jump>
</p>
<p>
Note that there is no standard API avaliable at the moment. SUN is
working on a JAVA Specification Request
<jump href="http://jcp.org/jsr/detail/105.jsp";>
JSR-105: XML Digital Signature APIs
</jump> on an API for XML Signature and
<jump href="http://jcp.org/jsr/detail/106.jsp";>
JSR-106: XML Digital Encryption APIs
</jump>, but until now, nothing has been published. So, this software
does <em>not</em> conform to any of these specifications.
</p>
</section>
<section>
<title>JDK 1.4 issues</title>
<p>
If you use JDK 1.4 and want to use this software, be sure that Xalan is
properly installed. Check the bottom of the <jump
href="site:java/installation">installation guide</jump>!!!
</p>
<p>
I have so many complaints from people who argue that the software
throws exceptions during running the examples or during unit
testing. This package NEEDS a Xalan version after 2.2D13 (and SUN
shipped his JDK 1.4.0 final with a Xalan beta!). I started integrating
the installation guide into the exception messages cause it seems that
people don't have a look at the installation guide.
</p>
</section>
</body>
</document>
1.1
xml-security/doc/site/src/documentation/content/xdocs/Java/installation.xml
Index: installation.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd"
[
<!ENTITY % xmlsec_entities SYSTEM "../xmlsec_entities.ent">
%xmlsec_entities;
]>
<document>
<header>
<title>Installation - Java</title>
</header>
<body>
<section>
<title>Using JDK 1.4.0</title>
<p>
After SUN released the
<jump href="ext:java">
Java (TM) 2 Platform Standard Edition v1.4.0
</jump>, the xml-security package stopped working. This is a
<jump
href="http://developer.java.sun.com/developer/bugParade/bugs/4615582.html";>
known
</jump>
problem: SUN packaged a beta of Xalan into the JDK 1.4.0, but the
xml-security package requires a stable version of Xalan (v2.2.0 or
later). To fix the problem, you have to put the xalan.jar into a
special directory in your JDK:
<code>j2sdk1.4.0/jre/lib/endorsed/xalan.jar</code> . If you installed
an out-of-the-box JDK1.4 (e.g. on Windows 2000), the "endorsed"
directory does not exist: you'll have to create it by hand.
</p>
<warning>
Putting this JAR to another location like <code>lib/ext</code> WILL
NOT WORK.
</warning>
<p>
For more on that, you can also check the
<jump href="http://xml.apache.org/~edwingo/jaxp-faq.html#override";>
Unofficial JAXP FAQ
</jump>.
</p>
</section>
<section>
<title>Prerequisites</title>
<p>
Make sure you get the Jakarta Ant Tool from
<jump href="ext:ant">http://jakarta.apache.org/ant/</jump>
</p>
</section>
<section>
<title>Getting the source</title>
<p>
You can download the sources via WWW in the distribution directory
under
<jump href="site:about/download">
http://xml.apache.org/security/dist/
</jump>
</p>
<p>
This project's CVS repository can be checked out through anonymous
(pserver) CVS with the following instruction set. The module you wish
to check out must be specified as the modulename. When prompted for a
password for anonymous, simply enter "anoncvs" without quotes:
</p>
<source>cvs -d :pserver:[EMAIL PROTECTED]:/home/cvspublic login
password: anoncvs
cvs -d :pserver:[EMAIL PROTECTED]:/home/cvspublic checkout
xml-security
</source>
<p>
A HTTP interface to browse the sources online is available via
<jump
href="site:getting-involved/CVS">http://cvs.apache.org/viewcvs.cgi/xml-security/</jump>
</p>
</section>
<section>
<title>Compiling the source</title>
<p>
At the command prompt type <code>ant test</code>. If you want to
use jikes instead of your default java compiler locate the
<code>build.xml</code>
file and replace the line
</p>
<source><property name="build.compiler" value="classic"/></source>
<p>
with
</p>
<source><property name="build.compiler" value="jikes"/></source>
</section>
<!-- Uncommented in the original docs
<section>
<title>Unpacking the files</title>
<p>
&packagename; is packaged as a ZIP file for all
platforms and operating systems. You can run the Java
<ref>jar</ref> command to unpack the distribution.
</p>
<ul>
<li>jar xf &packagename;-bin.&packageversion;.zip</li>
<li>jar xf &packagename;-src.&packageversion;.zip</li>
<li>This command creates a "&packagedirectory;" sub-directory in the
current directory containing all the files.</li>
</ul>
</section>
<section>
<title>Files in the binary package release</title>
<table>
<tr><td>LICENSE</td><td>License for &packagename;</td></tr>
<tr><td>Readme.html</td><td>Web page redirect to
docs/html/index.html</td></tr>
<tr><td>xerces.jar</td><td>Jar file containing all the parser class
files</td></tr>
<tr><td>xercesSamples.jar</td><td>Jar file containing all sample class
files</td></tr>
<tr><td>data/</td><td>Directory containing sample XML data
files</td></tr>
<tr><td>doc/html/</td><td>Directory containing documentation</td></tr>
<tr><td>doc/html/api/</td><td>Directory containing Javadoc API</td></tr>
</table>
<note>To use &packagename; you do not need the source files.</note>
</section>
-->
<section>
<title>Testing the distibution</title>
<p>
The first way to ensure that everything is in place is to run the unit
tests. This is simply done by typing <code>ant test</code>. This starts
the included JUnit test cases. Actually, we do not have complete test
coverage, but as a first start, it works.
</p>
</section>
<section>
<title>Playing around with the examples </title>
<p>
To see how the distribution works, simply run <code>ant
mega-sample</code> to let ant execute several examples from the
<code>src_samples/</code> directory.
</p>
</section>
<section>
<title>Files in the source package release</title>
<table>
<tr>
<td>build.xml</td>
<td>Top level <jump href="ext:ant">Ant</jump> Makefile -- read README
file before building</td>
</tr>
<tr>
<td>LICENSE.txt</td>
<td>License for the software</td>
</tr>
<tr>
<td>README</td>
<td>Build instructions</td>
</tr>
<tr>
<td>Readme.html</td>
<td>Web page redirect required for building documentation</td>
</tr>
<tr>
<td>STATUS</td>
<td>Current source code status information</td>
</tr>
<tr>
<td>data/</td>
<td>Directory containing sample data files and test vectors for the
unit tests</td>
</tr>
<tr>
<td>doc/xml/</td>
<td>Directory containing documentation, in XML form</td>
</tr>
<tr>
<td>src/</td>
<td>Directory containing source code for the core library</td>
</tr>
<tr>
<td>src_samples/</td>
<td>Directory containing source code for samples</td>
</tr>
<tr>
<td>src_unitTests/</td>
<td>Directory containing source code for unit tests</td>
</tr>
</table>
</section>
<section>
<title>Where is my JCE?</title>
<p>
There is <em>no</em> JCE bundled together with this
distribution. Living in Germany, I had no problem to include the JCE in
this software package but then I realized that the Apache Project is
hosted in the US where some export restrictions apply to the
cryptographic primitives.
</p>
<p>
Well, how do we solve this problem? The nice guys from the <jump
href="ext:bouncy">Bouncy Castle</jump> where so
helpful to supply the JAR that you need to create HMAC integrity checks
on their web site. When you use the ant makefile <code>build.xml</code>
and simply say <code>ant compile</code> or <code>ant get-jce</code>,
<code>ant</code> tries to fetch this JAR from the australian
server. After that step, the compilation works completely.
</p>
<p/>
<p>
The ant make tools initiates an automated download of the BouncyCastle
JCE. The file is downloaded into the libs/ directory and a "bc-" is
prepended to the filename. This is done because we want the provider
name (bc means BouncyCastle) being visible in the JAR's filename.
</p>
<p/>
<p>
If you are a little paranoid like all security people and don't want
ant to make automated downloads or your firewall doesn't permit it
(preventing programs "phoning home"), look in the
<code>./build.xml</code> file for the properties called
</p>
<p/>
<source><![CDATA[
<property name="jce.download.file"
value="]]>&jce_download_file;<![CDATA[ />
<property name="jce.download"
value="http://www.bouncycastle.org/download/${jce.download.file}"; />
<property name="lib.jce" value="${libs}/bc-${jce.download.file}" />
]]></source>
<p>
Here you can see that the file
<jump href="ext:java/jce/download/file">&jce_download_file;</jump>
is downloaded and stored in the location <code>&lib_jce;</code>
</p>
<p>
If you do this by hand (pointing you favourite web browser and download
it yourself), simply put a "<code>bc-</code>" in front of the filename
and put it to <code>./libs/</code>, then ant won't try to make a
download.
</p>
</section>
</body>
</document>
1.1
xml-security/doc/site/src/documentation/content/xdocs/Java/interop.xml
Index: interop.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd"
[
<!ENTITY % xmlsec_entities SYSTEM "../xmlsec_entities.ent">
%xmlsec_entities;
]>
<document>
<header>
<title>Java Interoperability</title>
</header>
<body>
<section>
<title>Problems</title>
<p>In Version v1.0.4, there is one test case which fails (interop test
for exclusive c14n). This is related to very esoteric node sets (The Y4
test vector from
<jump
href="http://www.w3.org/Signature/2002/02/01-exc-c14n-interop.html";>
the interop matrix
</jump>).
</p>
</section>
<section>
<title>Interoperability issues</title>
<p>
As it can be seen on the
<jump href="ext:w3c/xmldsig">working group homepage</jump>,
there are some interoperability reports, namely for
<jump href="http://www.w3.org/Signature/2000/10/10-c14n-interop.html";>
Canonical XML
</jump>,
<jump
href="http://www.w3.org/Signature/2002/02/01-exc-c14n-interop.html";>
Exclusive Canonical XML
</jump>
and
<jump
href="http://www.w3.org/TR/xmldsig-core/2001/04/05-xmldsig-interop.html";>
XML Signature
</jump>.
</p>
<p>
Interoperability depends heavily on test vectors, this means that
implementation A has to check whether the signatures from
implementation B can be verified. For this purpose, we have a
collection of different test vectors in our <code>data/</code>
directory. The directory includes test vectors from
</p>
<ul>
<li><jump href="http://www.baltimore.com/keytools/xml/index.html";>
Baltimore KeyTools XML</jump>
</li>
<li><jump href="http://jcewww.iaik.at/products/ixsil/index.php";>IAIK
IXSIL</jump></li>
<li><jump
href="http://www.rsasecurity.com/products/bsafe/certj.html";>
RSA Security Cert-J</jump>
</li>
<li>The vectors from the
<jump
href="http://www.alphaworks.ibm.com/tech/xmlsecuritysuite";>
IBM alphaWorks XML Security suite
</jump> could not been included in this distribution because of
licensing issues. For some reasons which I do not understand, they
copyrighted their test signatures which they have bundled with
xss4j. If you want to include interop testing against IBM in your
unit tests, simply do the following:
Download <code>xss4j-20011029.zip</code> from the
<jump
href="http://www.alphaworks.ibm.com/aw.nsf/download/xmlsecuritysuite";>
alphaWorks download page
</jump>.
Copy all files from the <code>xss4j-20011029.zip#/xss4j/data</code>
directory into the
<code>xml-security/data/com/ibm/xss4j-20011029/</code>
directory. If the
<jump href="api/org/apache/xml/security/test/InteropTest.html">
Interop
</jump> class finds these files, the
<code>org.apache.xml.security.test.interop.IBMTest</code> class is
also executed during unit interop tests.
</li>
</ul>
</section>
</body>
</document>
1.1
xml-security/doc/site/src/documentation/content/xdocs/Java/resolver.xml
Index: resolver.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd"
[
<!ENTITY % xmlsec_entities SYSTEM "../xmlsec_entities.ent">
%xmlsec_entities;
]>
<document>
<header>
<title>Resolver-Mania</title>
</header>
<body>
<section>
<title>Why do we need all these resolvers?</title>
<p>
For security and comfort reasons. In the XML Security package, there
exist many kinds of Resolvers for different purposes. Resolvers in this
package do the same job as an EntityResolver in the SAX package:
retrieve information from the apropriate location and give it to the
parser/software who needs it. The reason for offering these different
Resolvers is that it should be under complete control of the
application which connections to the network are made. In the security
area, it wouldn't be a good idea to imediately fetch some documents
from the web or make other connections only because you want to verify
a Signature. This resolver framework gives the application developer
the ability to have total control about the interface from the library
to the rest of the world.
</p>
</section>
<section>
<title>Types of resolvers</title>
<section>
<title>ResourceResolvers</title>
<p>
A
<jump href="&api_ref;utils/resolver/ResourceResolver.html">
ResourceResolver
</jump> is used by a
<jump href="&api_ref;signature/Reference.html">
Reference
</jump> to retrieve the signed resource from it's location. Different
resolvers exist to get signed portions from the XML document in which
the signature resides, to make HTTP connections or to fetch files
from the local file system. <br />
The concept of a
<jump href="&api_ref;utils/resolver/ResourceResolver.html">
ResourceResolver
</jump> is very similar to an org.xml.sax.EntityResolver, but in
contrast to that Interface, the ResourceResolver is able to
de-reference contents <em>inside</em> an XML document.
</p>
</section>
<section>
<title>StorageResolver</title>
<p>A
<jump href="&api_ref;keys/storage/StorageResolver.html">
StorageResolver
</jump> is used by
<jump href="&api_ref;keys/KeyInfo.html">
KeyInfo
</jump> and it's child objects / Elements to retrieve Certificates
from storage locations. This approach is used to allow a user to
customize the library for use in a specific corporate
environment. It's possible to write
<jump href="&api_ref;keys/storage/StorageResolver.html">
StorageResolver
</jump>s who make requests to LDAP servers or to use specificic PKI
interfaces. <br/>
Bundled with the software come three sample
<jump href="&api_ref;keys/storage/StorageResolver.html">
StorageResolver
</jump>s which can be used for common tasks:
</p>
<ul>
<li>
The
<jump
href="&api_ref;keys/storage/implementations/KeyStoreResolver.html">
KeyStoreResolver
</jump> is able to retrieve Certificates from a JAVA KeyStore
object. This
<jump
href="&api_ref;keys/storage/implementations/KeyStoreResolver.html">
KeyStoreResolver
</jump> is constructed from an open JAVA KeyStore.
</li>
<li>
The
<jump
href="&api_ref;keys/storage/implementations/SingleCertificateResolver.html">
SingleCertificateResolver
</jump> resolves only to a single Certificate. The
<jump
href="&api_ref;keys/storage/implementations/SingleCertificateResolver.html">
SingleCertificateResolver
</jump> is constructed using this single Certificate.
</li>
<li>
The
<jump
href="&api_ref;keys/storage/implementations/CertsInFilesystemDirectoryResolver.html">
CertsInFilesystemDirectoryResolver
</jump> is useful for resolving to raw X.509 certificates which
reside as separate files in a directory in the filesystem. Such a
resolver is needed for verifying the test signatures from Merlin
Huges which are bundled in a directory.
</li>
</ul>
<p>
<jump href="&api_ref;keys/storage/StorageResolver.html">
StorageResolver
</jump>s are supplied to the KeyInfo's
<code>addStorageResolver()</code> method.
</p>
<p>
Generally, a
<jump href="&api_ref;keys/storage/StorageResolver.html">
StorageResolver
</jump> has only a method to return an Iterator which iterates
through the available Certificates.
</p>
</section>
<section>
<title>KeyResolver</title>
<p>
A
<jump href="&api_ref;keys/keyresolver/KeyResolver.html">
KeyResolver
</jump> is used by
<jump href="&api_ref;keys/KeyInfo.html">
KeyInfo
</jump> to process it's child Elements. There exist two general
classes of a
<jump href="&api_ref;keys/keyresolver/KeyResolver.html">
KeyResolver
</jump>:
</p>
<ul>
<li>
If a ds:RSAKeyValue or ds:DSAKeyValue or ds:X509Certificate is used
inside the ds:KeyInfo, the resolvers can return a public key or
Certificate directly without further action, because the key itself
is contained inside the ds:Signature.
</li>
<li>
If there is only key material identification information like a
ds:KeyName or the serial number of the Certificate, the KeyResolver
must use the StorageResolvers to query the available keys and
certificates to find the correct one.
</li>
</ul>
<p>
Of course, there are cross-dependencies: e.g. a KeyResolver named
<jump
href="&api_ref;keys/keyresolver/implementations/RetrievalMethodResolver.html">
RetrievalMethodResolver
</jump> uses the
<jump href="&api_ref;utils/resolver/ResourceResolver.html">
ResourceResolver
</jump> framework to retrieve a public key or certificate from an
arbitrary location.
</p>
</section>
</section>
</body>
</document>
1.1
xml-security/doc/site/src/documentation/content/xdocs/c/credits.xml
Index: credits.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd">
<document>
<header>
<title>Credits</title>
</header>
<body>
<section>
<title>Software Used</title>
<p>
The XML-Security-C package makes heavy use of the Xalan-C and
Xerces-C++ libraries from the <jump
href="http://xml.apache.org";>
Apache Software Foundation XML Project</jump>.
</p>
<p>
This documentation has been created using Forrest, also part of
the Apache Sofware Foundation's XML project.
</p>
<p>
The package also makes heavy use of the <jump
href="http://www.openssl.org";>
OpenSSL</jump> cryptographic
libraries to provide the cryptographic foundation. The
associated
license can be found in the distribution in the doc/ directory.
</p>
</section>
</body>
</document>
1.1
xml-security/doc/site/src/documentation/content/xdocs/c/faq.xml
Index: faq.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE faqs PUBLIC "-//APACHE//DTD FAQ V1.1//EN" "dtd/faq-v11.dtd"
[
<!ENTITY % xmlsec_entities SYSTEM "../xmlsec_entities.ent">
%xmlsec_entities;
]>
<faqs title="Frequently Asked Questions - C++">
<part id="general_c">
<title>Compiling and Using the Library</title>
<faq id="openssl_c">
<question>
Is OpenSSL required?
</question>
<answer>
<p>
At this time, the xml-security-c library requires OpenSSL to
perform
cryptographic operations. However the library has been
written to
easily interface to other cryptographic providers. Future
versions
will provide interface layers to libgcrypt (the GNU Privacy
Guard
crypto library) and the Windows Crypto API.
</p>
</answer>
</faq>
<faq id="xalan_c">
<question>
Is Xalan required?
</question>
<answer>
<p>
The library can be compiled without linking to Xalan-c.
However
doing so will disable support for XPath and XSLT
transformations.
</p>
<p>
To disable Xalan-c support either use --without-xalan when
running
configure on UNIX, or use the VC++ "without Xalan" settings.
</p>
</answer>
</faq>
</part>
</faqs>
<!-- Keep this comment at the end of the file
Local variables:
mode: xml
sgml-omittag:nil
sgml-shorttag:nil
sgml-namecase-general:nil
sgml-general-insert-case:lower
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-parent-document:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
1.1
xml-security/doc/site/src/documentation/content/xdocs/c/index.xml
Index: index.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd">
<document>
<header>
<title>C++ Library Documentation</title>
</header>
<body>
<section>
<title>News</title>
<p>
The C++ library has now been fully transferred into the Apache XML
project. It was previously hosted on SourceForge.
</p>
<p>
The first release under Apache is 0.10. This is a Beta release,
with fairly complete documentation, and a stable code base. It
fully validates the various interop documents held in the xml-security
CVS, with the exception of those related to :
</p>
<ul>
<li>MD5 Digests (to be added in next point release)</li>
<li>XPath Filter (to be added in next point release)</li>
<li>XML Encryption (to be added post 1.00 release)</li>
</ul>
</section>
<section>
<title>Overview of the C++ Library</title>
<p>
The C++ library is an implementation of the XML Digital Signature
specification. It is designed to be easily ported to new platforms,
and has been tested on Solaris, Linux and Windows. The next version
will have ports to FreeBSD and HP-UX.
</p>
<p>
The library makes use of the Apache XML project's Xerces-C XML Parser
and Xalan-C XSLT processor. The latter is used for processing XPath
and XSLT transforms. The use of Xalan-C is optional, but without it,
XPath and XSLT transformations cannot be performed.
</p>
<p>
In addition, the library currently uses OpenSSL to provide
cryptographic functionality. The cryptographic interface is
implemented via a thin wrapper layer, which will be expanded to
support the GNU Privacy Guard cryptographic library (libgcrypt) and
Windows CAPI in the near future.
</p>
</section>
</body>
</document>
<!-- Keep this comment at the end of the file
Local variables:
mode: xml
sgml-omittag:nil
sgml-shorttag:nil
sgml-namecase-general:nil
sgml-general-insert-case:lower
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-parent-document:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
1.1
xml-security/doc/site/src/documentation/content/xdocs/c/installation.xml
Index: installation.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd"
[
<!ENTITY % xmlsec_entities SYSTEM "../xmlsec_entities.ent">
%xmlsec_entities;
]>
<document>
<header>
<title>Installing the C++ Library</title>
</header>
<body>
<section>
<title>Prerequisites</title>
<p>
The library requires OpenSSL for cryptographic support. Xalan-C
is also required if XPath and/or XSLT transformations are
required.
</p>
</section>
<section>
<title>Getting the source</title>
<p>
You can download the sources via WWW in the distribution directory
from one of the Apache
<jump href="site:about/download">
mirrors
</jump>.
</p>
<p>
This project's CVS repository can be checked out through anonymous
(pserver) CVS with the following instruction set. The module you wish
to check out must be specified as the modulename. When prompted for a
password for anonymous, simply enter "anoncvs" without quotes:
</p>
<source>cvs -d :pserver:[EMAIL PROTECTED]:/home/cvspublic login
password: anoncvs
cvs -d :pserver:[EMAIL PROTECTED]:/home/cvspublic checkout
xml-security
</source>
<p>
A HTTP interface to browse the sources online is available via
<jump
href="site:getting-involved/CVS">http://cvs.apache.org/viewcvs.cgi/xml-security/</jump>
</p>
</section>
<section>
<title>Building for UNIX</title>
<p>
XML-Security-C is currently supported on Linux and Solaris.
It has been built and tested using GNU gcc 2.95.4 and GNU make.
</p>
<note>
The UNIX XML-Security-C build process has changed radically
since
beta 0.0.2 as the Makefiles and configure scripts have been
completely
rewritten.
</note>
<section>
<title>Set up the Environment</title>
<p>
The build process has been automated as much as possible. To
start the process, three environment variables <em>can</em>
be set :
</p>
<ul>
<li><em>XERCESCROOT</em> - points to the base of your Xerces
distribution</li>
<li><em>XALANCROOT</em> - points to the base of your Xalan
distribution</li>
<li><em>OPENSSL</em> - points to the base of your OpenSSL
distribution</li>
</ul>
<p>
For example (on my Debian Linux box under Bash) :
</p>
<source><![CDATA[
export XERCESCROOT=~/prog/extlibs/xerces-c-src2_2_0
export XALANCROOT=~/prog/extlibs/xalan-c-src1_5/c
export OPENSSL=~/prog/extlibs/openssl-0.9.7a
]]></source>
<p>
If these environment variables are not set, configure will
try to
find the necessary include and library files in the system
directories.
The configure script is created through <em>autoconf</em> so
you
can also tell your compiler where to find these things via
the <em>CXXFLAGS</em> and <em>LDFLAGS</em> environment
variables.
</p>
<p>
If configure cannot find anything for Xalan, it will assume
that
you are not interested in XPath or XSLT support and will
compile
XSEC without linking to Xalan. Any attempt to use these
features
will raise an exception in the library.
</p>
</section>
<section>
<title>Configure</title>
<p>
Now go to the $XSECCROOT/src directory and run the command
<em>./configure</em>. This will create the necessary
makefiles
and header files necessary to build the package.
</p>
<p>
In addition to the standard options, <em>configure</em> can
be
passed a number of XSEC specific options :
</p>
<ul>
<li><em>--without-xalan</em> disable linkage to Xalan.</li>
<li><em>--enable-debug</em> cause the library to be built
with symbols</li>
</ul>
<note>
Using the <em>--without-xalan</em> option will automatically
mean
that the library does not support XPath or XSLT
transformations
(although envelope transforms will work as the library can now
perform these without going through an XPath transform).
</note>
</section>
<section>
<title>Compile</title>
<p>
Assuming the output of the above command looks reasonable
simply
type <em>make</em> (or <em>gmake</em> - you must use the GNU
make utility) in the <em>src</em> directory. This
will make the shared library. In addition, <em>make
tools</em>
will make the tools (or examples) in the src/tools directory.
</p>
<p>
The make process will create three directories in the
distribution
directory:
</p>
<ol>
<li><em>include</em> - All public header files are copied
here</li>
<li><em>bin</em> - Where the tools are placed once compiles
</li>
<li><em>lib</em> - Where the shared library is place</li>
</ol>
<p>
You will need to set up your <em>LD_LIBRARY_PATH</em>
environment
variable to ensure ld.so will find the new shared libraries.
</p>
<p>
Finally - you can use <em>make clean</em> and <em>make
distclean</em>
to remove all binaries and libraries (former) and build
scripts (latter)
</p>
</section>
</section>
<section>
<title>Building for Windows</title>
<p>
XML-Security-C has been built and tested on Microsoft's Visual
C++ 6.0
compiler only. (VC++ .NET support is currently being worked
on.)
The following subsections briefly describe how to
rebuild the library, tools and samples using the supplied
workspaces.
</p>
<section>
<title>Setup Directories</title>
<p>
The workspace and project files provided do not make any
assumptions
about where Xerces, Xalan or OpenSSL might be on the system.
The
first step is therefore to configure VC directories under
Tools->Options (Directories).
</p>
<p>
For the Include directories you will need something similar
to my
setup below (replacing D:\PROG\CLIB\.. with the appropriate
path
on your system).
</p>
<figure src="images/vc6a.gif" alt="Include Directories"/>
<p>
Similarly the library directories will need to be added to.
Note
that in the example below, I use both Debug and Release
libraries
for Xalan and Xerces. As provided, the workspace projects
link to
the debug libraries for XSEC Debug and Release for XSEC
Release.
</p>
<figure src="images/vc6b.gif" alt="Link Directories"/>
</section>
<section>
<title>Build Library and Tools</title>
<p>
The main workspace is found in :
</p>
<p><em>.../src/Projects/VC6.0/xsec/xsec.dsw</em></p>
<p>
You can load this to build the tools or the library using the
relevant
project. (The library is xsec_lib.)
</p>
<p>
Samples can be built using the workspace found in :
</p>
<p><em>.../src/Projects/VC6.0/Samples/Samples.dsw</em></p>
<p>All output will be sent to</p>
<p><em>.../Build/Win32/VC6/Debug</em></p>
<p>for the debug builds and Release for the release.</p>
</section>
</section>
</body>
</document>
<!-- Keep this comment at the end of the file
Local variables:
mode: xml
sgml-omittag:nil
sgml-shorttag:nil
sgml-namecase-general:nil
sgml-general-insert-case:lower
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-parent-document:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
1.1
xml-security/doc/site/src/documentation/content/xdocs/c/interop.xml
Index: interop.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd"
[
<!ENTITY % xmlsec_entities SYSTEM "../xmlsec_entities.ent">
%xmlsec_entities;
]>
<document>
<header>
<title>C++ Interoperability</title>
</header>
<body>
<section>
<title>Interoperability</title>
<p>
The C++ library is designed to be fully inter-operable with any
other implementation of the W3C XML Digital Signature standard, such
as the Apache XML-Security Java library.
</p>
</section>
</body>
</document>
<!-- Keep this comment at the end of the file
Local variables:
mode: xml
sgml-omittag:nil
sgml-shorttag:nil
sgml-namecase-general:nil
sgml-general-insert-case:lower
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-parent-document:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
1.1
xml-security/doc/site/src/documentation/content/xdocs/c/programming.xml
Index: programming.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd">
<document>
<header>
<title>Programming</title>
</header>
<body>
<section>
<title>Overview</title>
<p>
There are two main modes of operation for the libraries.
Signing and
verifying. Verifying is the simplest operation, as it
(generally)
operates on a DOM <Signature> structure that has already
been
created.
</p>
<p>
Signing on the other hand can be more difficult, as there may
be a
requirement to create the DOM structure necessary for the
signature
prior to the actual signing operation.
</p>
<p>
The rest of this section provides a very high level overview on
how
to use the library for signing and verificataion of signatures.
</p>
<p>
Two samples are provided :
</p>
<ul>
<li><link href="programming.html#simplehmac">Simple HMAC Signing
</link></li>
<li><link href="programming.html#simpledsa">Simple DSA
Validation
</link></li>
</ul>
<p>
The code snippets are taken directly from some of the sample
code
provided in the src/samples directory in the distribution.
More
information on the API can be found in the API Documentation.
</p>
</section>
<section id="simplehmac">
<title>A simple HMAC Signing example</title>
<p>
The first example is based on the simpleHMAC.cpp code in
samples. It
creates an XML letter, the appends a dummy signature to the
end, using
an enveloped-signature transform.
</p>
<section>
<title>Setup</title>
<p>
The following code snippet initialises Xerces, Xalan and XSEC.
Note that the enveloped transform is implemented using an
XPath
expression, so it is imperitive the Xalan libraries are
initialised.
</p>
<source><![CDATA[
int main (int argc, char **argv) {
try {
XMLPlatformUtils::Initialize();
#ifndef XSEC_NO_XALAN
XalanTransformer::initialize();
#endif
XSECPlatformUtils::Initialise();
}
catch (const XMLException &e) {
cerr << "Error during initialisation of Xerces" << endl;
cerr << "Error Message = : "
<< e.getMessage() << endl;
}
// Create a blank Document
DOMImplementation *impl =
DOMImplementationRegistry::getDOMImplementation(MAKE_UNICODE_STRING("Core"));
// Create a letter
DOMDocument *doc = createLetter(impl);
DOMElement *rootElem = doc->getDocumentElement();
]]></source>
<p>
In the sample application, the call to
<em>createLetter(impl)</em>
simply creates a
letter DOM structure with a to and from address and some text.
This is done using standard DOM calls via Xerces.
</p>
<p>
Once the system is initialised and the DOM document is
created,
a DSIGSignature object is created via the
<em>XSECProvider</em>
interface class. The signature object is then used to create
a blank signature DOM node structure which is then inserted
at
the end of the document.
</p>
<source><![CDATA[
XSECProvider prov;
DSIGSignature *sig;
DOMElement *sigNode;
try {
// Create a signature object
sig = prov.newSignature();
sig->setDSIGNSPrefix("ds");
// Use it to create a blank signature DOM structure from the doc
sigNode = sig->createBlankSignature(doc,
CANON_C14N_COM,
SIGNATURE_HMAC,
HASH_SHA1);
]]></source>
<p>
The call to <em>newSignature</em> creates a signature
object only. No DOM nodes are created at this point.
The call to <em>setDSIGNSPrefix</em> tells the XSEC
library what namespace prefix to use for the signature object
when
it starts to create DOM nodes (in this case "ds" will be
used).
By default, the library will use "dsig" as the prefix for the
name
space for Digital Signatures.
</p>
<p>
Finally, the call to sig->createBlankSignature sets up both
the
DOM structure and the XSEC objects for a new signature with no
<Reference> elements. In this case, the signature will
be
made using Commented C14n canonicalisation, and a HMAC-SHA1
signature.
</p>
<warning>
The XSECProvider class still "owns" the DSIGSignature object.
To delete the object, the original provider.release(sig) call
should be used. Never delete a DSIGSignature object directly.
</warning>
</section>
<section>
<title>Create a Reference and Sign</title>
<p>
Now that the signature object is created, the signature is
inserted
into the document, and a reference is created and set for an
enveloping transform.
</p>
<source><![CDATA[
// Insert the signature DOM nodes into the doc
rootElem->appendChild(doc->createTextNode(MAKE_UNICODE_STRING("\n")));
rootElem->appendChild(sigNode);
rootElem->appendChild(doc->createTextNode(MAKE_UNICODE_STRING("\n")));
// Create an envelope reference for the text to be signed
DSIGReference * ref = sig->createReference("");
ref->appendEnvelopedSignatureTransform();
]]></source>
<p>
The <em>""</em> parameter to <em>createReference</em> sets the
URI attribute for the reference to be "" - indicating the root
element of the document in which the signature resides.
The call to <em>appendEnvelopedSignatureTransform</em> adds
a standard eneveloped-signature transform to the Reference
node.
</p>
<p>
The macro MAKE_UNICODE_STRING is defined within the library
header files and is used to transcode local code page strings.
</p>
<note>
There is no need to insert the reference object into the DOM
structure.
This is done automatically by the <em>createReference</em>
call.
</note>
<p>
Finally we create a signing key and sign the document.
</p>
<source><![CDATA[
// Set the HMAC Key to be the string "secret"
OpenSSLCryptoKeyHMAC * hmacKey = new OpenSSLCryptoKeyHMAC();
hmacKey->setKey((unsigned char *) "secret", strlen("secret"));
sig->setSigningKey(hmacKey);
// Add a KeyInfo element
sig->appendKeyName("The secret key is \"secret\"");
// Sign
sig->sign();
}
catch (XSECException &e)
{
cerr << "An error occured during a signature load\n Message: "
<< e.getMsg() << endl;
exit(1);
}
]]></source>
<p>
The first two code lines create an OpenSSLCryptoKeyHMAC
object,
and set the key value to the string "secret". The OpenSSL...
classes are the interface layer between XSEC and OpenSSL.
More
information can be found in the API documentation, but the
main
point of note is that the XSEC library never deals directly
with
OpenSSL - it works via the XSECCrypto abstract classes which
are
implemented in the OpenSSLCrypto code. This would allow
another
person to re-implement the XSECCrypto code to use any
cryptographic
provider required.
</p>
<note>
Once the key is passed to the signature it is owned by the
signature.
The signature object will delete the key when it is itself
deleted,
or a new key is passed in.
</note>
<p>
The call to <em>sig->appendKeyName()</em> is used to append a
<KeyName> element into the <KeyInfo> block. The
KeyInfo block was created as part of this call.
</p>
<p>
After the call to <em>sig->sign()</em> the DOM structure has
the
correct hash and signature values. The owner program can
write,
store or further manipulate the document as required. If a
document
manipulation might affect the signature (in this case almost
anything
would, as we are using an enveloping transform which
effectively
signs everything that is not part of the signature), then a
further
call to <em>sig->sign()</em> will re-sign the changes.
</p>
<p>
The last part of the code does some work to output the new DOM
structure. The output should look something like the
following:
</p>
<source><![CDATA[
<Letter>
<ToAddress>The address of the Recipient</ToAddress>
<FromAddress>The address of the Sender</FromAddress>
<Text>
To whom it may concern
...
</Text>
<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#";>
<ds:SignedInfo>
<ds:CanonicalizationMethod Algorithm=
"http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments"/>
<ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#hmac-sha1"/>
<ds:Reference URI="">
<ds:Transforms>
<ds:Transform Algorithm=
"http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
</ds:Transforms>
<ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
<ds:DigestValue>askxS/A3BaLCjFjZ/ttU9c12kA4=</ds:DigestValue>
</ds:Reference>
</ds:SignedInfo>
<ds:SignatureValue>oYEdQYG1IHzbkR1UcJ9Q5VriRPs=
</ds:SignatureValue>
<ds:KeyInfo>
<ds:KeyName>The secret key is "secret"</ds:KeyName>
</ds:KeyInfo>
</ds:Signature>
</Letter>
]]></source>
<p>Note that the DigestValue and SignatureValue elements have
been
filled in.
</p>
</section>
</section>
<section id="simpledsa">
<title>A simple validation example</title>
<p>
The second example takes a pre-signed document and an associated
certificate and verifies the embedded signature. The document
in
question is a simple purchase order, and changes are made to the
value of the order to demonstrate a signature failing
verification.
</p>
<section>
<title>Setup</title>
<p>
As in the first example, Initialisation of the libraries is
performed, and Xerces is used to read in the document (which
in
this case is stored in a string in the source code).
</p>
<p>
In order to be able to modify the contents of the document
later
on, we also quickly find the string containing the value of
the
purchase order.
</p>
<p>
For the sake of brevity, the code relating to parsing the
in-memory
document has been removed from the snippet below.
</p>
<source><![CDATA[
int main (int argc, char **argv) {
try {
XMLPlatformUtils::Initialize();
#ifndef XSEC_NO_XALAN
XalanTransformer::initialize();
#endif
XSECPlatformUtils::Initialise();
}
catch (const XMLException &e) {
cerr << "Error during initialisation of Xerces" << endl;
cerr << "Error Message = : "
<< DOMString(e.getMessage()) << endl;
}
...
Xerces is used to parse the document here
DOM_Document doc = parser->getDocument();
// Find the Amount node
DOMNode *amt = doc->getDocumentElement();
if (amt != NULL)
amt = amt->getFirstChild();
while (amt != NULL &&
(amt->getNodeType() != DOMNode::ELEMENT_NODE ||
!strEquals(amt->getNodeName(), "Amount")))
amt = amt->getNextSibling();
if (amt != NULL)
amt = amt->getFirstChild();
if (amt == NULL || amt->getNodeType() != DOMNode::TEXT_NODE) {
cerr << "Error finding amount in purchase order" << endl;
exit (1);
}
]]></source>
</section>
<section>
<title>Create the Signature and Key objects</title>
<p>
Now that the document is in memory, an XSECProvider is
created and used to create a new DSIGSignature object. In
addition, the OpenSSL interface routines are used to
read in a certificate and obtain the associated public
key.
</p>
<source><![CDATA[
XSECProvider prov;
DSIGSignature * sig = prov.newSignatureFromDOM(doc);
try {
// Use the OpenSSL interface objects to get a signing key
OpenSSLCryptoX509 * x509 = new OpenSSLCryptoX509();
x509->loadX509Base64Bin(cert, strlen(cert));
sig->load();
]]></source>
<p>
In this case, the signature is create with the
<em>newSignatureFromDOM</em> method. This tells the library
that
the signature structure (although not necessarily a signed
structure) already exists in the DOM nodes. The library
attempts
to find the <Signature> node so that the load will work.
(The library will throw an XSECException if it cannot find the
Element.)
</p>
<p>
The later call to <em>sig->load()</em> tells the library to
read the DOM structure and create the appropriate DSIG
elements.
</p>
<p>
In this case an OpenSSLCryptoX509 object is also created. It
is
used to read in the <em>cert</em> string and convert to an
X509
structure. This could also be done using standard calls
directly
to OpenSSL, but this is a quick shortcut.
</p>
</section>
<section>
<title>Find a key</title>
<p>
As we already know the key, the following code snippet loads
the
key directly from the related X509. However prior to doing
this,
the code demonstrates
using the DSIGKeyInfo structures to find the key name that was
embedded in the certificate. In an application, this could be
used to reference the correct key to be passed in. (Maybe via
an XKMS call.)
</p>
<p>
the <em>safeBuffer</em> type is used extensively within the
XSEC
library to safely handle variable length strings and raw
buffers.
The call to <em>rawCharBuffer()</em> simply returns a (char *)
type pointer to the buffer within the <em>safeBuffer</em>
</p>
<p>
The call to <em>clonePublicKey()</em> returns a copy of the
public key embedded in the certificate. It is owned by the
caller,
so in this case it can safely be passed to the DSIGSignature
object
where it will be destroyed when another key is loaded or the
object is released by the XSECProvider.
</p>
<source><![CDATA[
DSIGKeyInfoList * kinfList = sig->getKeyInfoList();
// See if we can find a Key Name
safeBuffer kname;
DSIGKeyInfo * kinf = kinfList->getFirstKeyInfo();
while (kinf != NULL) {
kname = kinf->getKeyName();
if (kname.sbStrcmp("")) {
cout << "Key Name = "
<< kname.rawCharBuffer() << endl;
}
kinf = kinfList->getNextKeyInfo();
}
sig->setSigningKey(x509->clonePublicKey());
]]></source>
</section>
<section>
<title>Validate the signature</title>
<p>
Finally the signature is validated. In this case, we
validate it
three times. First with the original DOM structure, then
with the
price changed and finally with the price set back to the
original
value.
</p>
<source><![CDATA[
cout << "Amount = " << amt << " -> ";
if (sig->verify()) {
cout << "Signature Valid\n";
}
else {
cout << "Incorrect Signature\n";
}
amt.setNodeValue("$0.50");
cout << "Amount = " << amt << " -> ";
if (sig->verify()) {
cout << "Signature Valid\n";
}
else {
cout << "Incorrect Signature\n";
}
amt.setNodeValue("$16.50");
cout << "Amount = " << amt << " -> ";
if (sig->verify()) {
cout << "Signature Valid\n";
}
else {
cout << "Incorrect Signature\n";
}
]]></source>
<p>
When run, the program outputs the following:
</p>
<source><![CDATA[
Key Name = C=AU, ST=Vic, O=XML-Security-C Project,
CN=Samples Demo Certificate
Amount = $16.50 -> Signature Valid
Amount = $0.50 -> Incorrect Signature
Amount = $16.50 -> Signature Valid
]]></source>
</section>
</section>
</body>
</document>
1.1
xml-security/doc/site/src/documentation/content/xdocs/c/releases.xml
Index: releases.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd">
<document>
<header>
<title>Release Information</title>
</header>
<body>
<section>
<title>Changes</title>
<p>
This section describes the changes that have occurred between
the
various releases of the library
</p>
<section>
<title>Current Release - Beta 0.10</title>
<p>
The current release of the xml-security-c library is a beta
of the
XML Digital Signature code, and is the first version of the
library
produced within Apache's XML project.
</p>
<p>
Previous versions were created within Sourceforge as the
xml-security-c project at that site.
</p>
</section>
<section>
<title>Changes from 0.03-0.10</title>
<p>
The following changes occurred between versions 0.03 and 0.10
:
</p>
<ul>
<li>A <em>threadTest</em> tool, which is primarily used to
show
how multiple threads can access the library under
Windows</li>
<li>Windows and UNIX URI Resolvers, based on the Xerces
resolver,
but which can handle HTTP re-directs</li>
<li>Completed a basic level of API documentation</li>
<li>Reviewed library to ensure usage of UTF-16 internally</li>
<li>Closed a number of memory-leaks caused by exceptions being
thrown</li>
</ul>
</section>
<section>
<title>Changes from 0.02-0.03</title>
<p>
The following changes occurred between 0.02->0.03
</p>
<ul>
<li>A <em>txfmout</em> tool to output the transformed
references</li>
<li>Updates to <em>templatesign</em> to support KeyInfo
elements
and RSA signatures</li>
<li>Library support for RSA signatures</li>
<li>API support form manipulating KeyInfo elements</li>
<li>Pluggable KeyInfo Resolvers (to allow an application to
supply
an object that will resolve a given KeyInfo to a
key)</li>
<li>Pluggable URI resolvers</li>
<li>API support for creating references and
transformations</li>
<li>Re-written Makefiles for *NIX</li>
<li>Improved API docs</li>
<li>Envelope Transform that no longer uses XPath transforms
(much
quicker)</li>
<li>Uses new Xerces DOMNode objects - has made for significant
speed improvements</li>
</ul>
</section>
<section>
<title>Changes from 0.01-0.02</title>
<ul>
<li>Signing functionality</li>
<li>Update C14n canonicalisation</li>
<li>Exclusive Canonicalisation</li>
<li>Basic ability to create a signature via the API (rather
than just
from an XML template file</li>
<li>SHA-1 HMAC support</li>
<li>Basic Documentation of core API</li>
<li>A <em>templatesign</em> tool</li>
</ul>
</section>
</section>
<section>
<title>Future Release Plans</title>
<p>
The current plans are to stablise the beta code and provide a
sound
core library for digital signing. Now that the code is at 0.10,
some further additions will be made to the digital signature
support,
and a 1.00 release will be made when digital signature support
is
fairly complete.
</p>
<p>
XML Encryption will be added post 1.00
</p>
<p>
The majority of activity from now to 1.00 will concentrate on:
</p>
<ul>
<li>Fixing bugs and memory leaks</li>
<li>Ensure API is reasonably consistant</li>
<li>Improvements in the API for manipulating a signature
in memory</li>
<li>Support for KeyInfo elements not currently implemented (PGP
and
SPKI)</li>
<li>Implementation of libgcrypt as a crypto provider</li>
<li>Support for PGP/GPG signatures (using libgcrypt and
gpgme)</li>
<li>NetBSD/FreeBSD builds</li>
<li>Install capability in make files</li>
</ul>
</section>
<section>
<title>Beyond a stable release</title>
<p>A number of items are planned for after the 1.0 major release.</p>
<ul>
<li>XML Encryption Support</li>
<li>A crypto interface for the Windows CAPI</li>
<li>Implementation of a core set of encryption primitives to
allow
decoupling from OpenSSL for "light" applications</li>
<li>Improved <em>KeyInfo</em> resolver interface leading
to...</li>
<li>XKMS client support</li>
<li>Bring the API in-line with JCP 105 (if appropriate)</li>
<li>Eventually (the GRAND PLAN) an XKMS server
implementation</li>
</ul>
</section>
</body>
</document>
<!-- Keep this comment at the end of the file
Local variables:
mode: xml
sgml-omittag:nil
sgml-shorttag:nil
sgml-namecase-general:nil
sgml-general-insert-case:lower
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-parent-document:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
1.1
xml-security/doc/site/src/documentation/content/xdocs/c/tools.xml
Index: tools.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd">
<document>
<header>
<title>Tools</title>
</header>
<body>
<section>
<title>Provided Tools</title>
<p>
A number of very simple "tools" (really examples) are provided
with
the XML Security library. These can be used either to provide
examples
of how to use the library or as simple utilities in their own
right for
performing canonicalisation and signature functions.
</p>
<p>
The tools are :
</p>
<ul>
<li><em>c14n</em> - A tool to output a Canonicalised version of
an
input document.</li>
<li><em>checksig</em> - A tool to validate a signature in an XML
input document</li>
<li><em>templatesign</em> - A tool to sign an XML document that
already
has the <Signature> structure installed, but needs the
references
hashed and the SignatureValue set.</li>
<li><em>txfmout</em> - A tool to take an XML Signature and
output
the fully transformed references to stdout or a nominated
file</li>
<li><em>threadTest</em> - A Windows only program that runs up a
number
of threads which simultaneously sign and validate documents.
A
number of documents are modified in between (to cause the
signature
validation to fail).</li>
</ul>
<p>
The tools can all be run with no command line arguments to see
their
parameters.
</p>
<p>
One extra "tool" is provided - <em>xtest</em>. This is really
a testing
program that exercises various capabilities of the library and
compares
the results with known good results.
</p>
</section>
</body>
</document>
<!-- Keep this comment at the end of the file
Local variables:
mode: xml
sgml-omittag:nil
sgml-shorttag:nil
sgml-namecase-general:nil
sgml-general-insert-case:lower
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-parent-document:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
1.1
xml-security/doc/site/src/documentation/resources/images/group-logo.gif
<<Binary file>>
1.1
xml-security/doc/site/src/documentation/resources/images/icon.png
<<Binary file>>
1.1
xml-security/doc/site/src/documentation/resources/images/project-logo.gif
<<Binary file>>
1.1
xml-security/doc/site/src/documentation/resources/images/vc6a.gif
<<Binary file>>
1.1
xml-security/doc/site/src/documentation/resources/images/vc6b.gif
<<Binary file>>
