Author: raul Date: Tue Jan 23 01:42:12 2007 New Revision: 498968 URL: http://svn.apache.org/viewvc?view=rev&rev=498968 Log: Updating web pages for 1.4 release Added: xml/site/targets/security/Java/api.html xml/site/targets/security/Java/examples.html xml/site/targets/security/Java/faq.html xml/site/targets/security/Java/index.html xml/site/targets/security/Java/installation.html xml/site/targets/security/Java/interop.html xml/site/targets/security/Java/resolver.html Added: xml/site/targets/security/Java/api.html URL: http://svn.apache.org/viewvc/xml/site/targets/security/Java/api.html?view=auto&rev=498968 ============================================================================== --- xml/site/targets/security/Java/api.html (added) +++ xml/site/targets/security/Java/api.html Tue Jan 23 01:42:12 2007 @@ -0,0 +1,195 @@ + + + + + + + +Java API Documentation + + + + + + + + +
+ +
+apache > xml.apache +
+ +
+ + + + + + + + + + + + +
+
+
+
+ +
+ + +
+ +
+ +   +
+ + + + + +
+ +

Java API Documentation

+ + +

Javadoc Generated Documentation

+
+

Apache-XML-Security-J comes packaged with API documentation.

+

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.

+
+ + +

xml-security API Documentation

+ + +
+ +
 
+
+ + + Added: xml/site/targets/security/Java/examples.html URL: http://svn.apache.org/viewvc/xml/site/targets/security/Java/examples.html?view=auto&rev=498968 ============================================================================== --- xml/site/targets/security/Java/examples.html (added) +++ xml/site/targets/security/Java/examples.html Tue Jan 23 01:42:12 2007 @@ -0,0 +1,205 @@ + + + + + + + +Java Examples + + + + + + + + +
+ +
+apache > xml.apache +
+ +
+ + + + + + + + + + + + +
+
+
+
+ +
+ + +
+ +
+ +   +
+ + + + + +
+ +

Java Examples

+ + +

XML Signatures

+
+

+ 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 src_samples/ directory to give interested users a + first starting point to jump-start with XML Signature. +

+
+
Note
+
+ The samples divide into two groups: Samples that create and + samples that verify Signatures. Eventually, you should adjust + the verifying program to another filename if you get + FileNotFoundExceptions. +
+
+
+ + +

XML Encryption

+
+

+ As with signatures, samples are provided to show how to encrypt + and decrypt XML content. See + src_samples/org/apache/xml/security/samples/encryption. +

+

+ The samples can be compiled and run using ant encrypt + and ant decrypt. +

+
+ +
+ +
 
+
+ + + Added: xml/site/targets/security/Java/faq.html URL: http://svn.apache.org/viewvc/xml/site/targets/security/Java/faq.html?view=auto&rev=498968 ============================================================================== --- xml/site/targets/security/Java/faq.html (added) +++ xml/site/targets/security/Java/faq.html Tue Jan 23 01:42:12 2007 @@ -0,0 +1,457 @@ + + + + + + + +Frequently Asked Questions - Java + + + + + + + + +
+ +
+apache > xml.apache +
+ +
+ + + + + + + + + + + + +
+
+
+
+ +
+ + +
+ +
+ +   +
+ + + + + +
+ +

Frequently Asked Questions - Java

+ +

Questions

+
+ +

1. Questions about Java

+ +

1.1. + I have a Java-(security/cryptography) problem. Can you help me? +

+
+^ +
+
+

+ Go to the java forum of Sun. You can + find forums where you can ask questions like "How do I generate + a keypair", etc. +

+
+ +

1.2. + I have a Java-XML problem. +

+
+^ +
+
+

+ Go to the java forum of Sun, section + Java Technology & XML and have a look at Apache Xerces. +

+
+ +

2. Questions about this package

+ +

2.1. + I'm using Crimson, but it throws Exceptions. Why? +

+
+^ +
+
+

+ Crimson is not supported at the moment. The main reason is that + Crimson did not support the + org.w3c.dom.traversal.TreeWalker interface in the + past. Additionally, it does not support the + org.apache.xerces.dom.DocumentImpl.putIdentifier(String ID, + Element e) functionality where Xerces allows us to enable ID + attributes during document generation. +

+

+ Use Apache Xerces + instead of Crimson. +

+
+ +

2.2. + What's up with the Bouncy Castle CSP? / Where is my CSP? +

+
+^ +
+
+

+ There is no 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. +

+

+ The nice guys from the Legion of Bouncy + Castle 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 libs/ directory. When you use the + ant makefile build.xml and simply say ant + compile or ant get-jce, ant tries + to fetch this JAR from the australian server. After that step, the + compilation works completely. +

+

+ 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. +

+
+
Note
+
+ The fact that we use Bouncy in this project does not mean + that you must use it, it's only the default. If you take a + look at the configuration + src/org/apache/xml/security/resource/config.xml, you'll + notice the sections which do integrate these alternative JCEs. +
+
+

+ More information can be found in the Installation section. +

+
+ +

2.3. + How do I enable/turn off logging? +

+
+^ +
+
+

+ The logging is configured in the config.xml file which + either in the xmlsec.jar 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 ;-)) +

+

OK, so it goes: In the + + xml-security/src/org/apache/xml/security/resource/config.xml + file, there is an element called + <log4j:configuration>. This element contains the + XML style configuration information as defined in the + + log4j DOMConfigurator class + . You can find examples + here + +

+
+ +

2.4. + What is the meaning of BaseURI? +

+
+^ +
+
+

+ When you work with URIs like + "http://www.example.com/index.html", 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 + "../1.txt", it's not possible to understand + this reference without some context. This context is the + BaseURI. For instance, if you sign + URI="../1.txt" and the + BaseURI="file:///home/user/work/signature.xml", + it is clear that the file + BaseURI="file:///home/user/1.txt" is to be + signed. But when you create the signature, the file + BaseURI="file:///home/user/work/signature.xml" + does not yet exist; therefore, you have to supply the URL where you + intend to store the signature later (relative to the signed objects). +

+

+ 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 + Reference elements which point to the filesystem or + something similar. +

+

+ Example: Imagine that you want to create a signature to store it on a + web server as + http://www.acme.com/signatures/sig1.xml. So + BaseURI="http://www.acme.com/sig1.xml". This + means that if you create a Reference with + URI="./index.html", the library can easily use + it's HTTPResourceResolver to fetch + http://www.acme.com/index.html without that you have to + say URI="http://www.acme.com/index.html". +

+
+ +

2.5. + How do I use the package to generate and verify a signature? +

+
+^ +
+
+

+ Checkout the samples in + src_samples/org/apache/xml/security/samples/signature/. +

+
+
Note
+
+ The samples divide into two groups: Samples that create and + samples that verify Signatures. Eventually, you should + adjust the verifying program to another filename if you get + FileNotFoundExceptions. +
+
+
+ +

2.6. + I'm using SUN JDK v1.4.0 or v1.4.1 and it get some exceptions. Any clues? +

+
+^ +
+
+

+ After SUN released the Java (TM) 2 Platform + Standard Edition v1.4.0 , the xml-security package stopped + working. This is a + + known + + 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: + j2sdk1.4.0/jre/lib/endorsed/xalan.jar. 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. +

+
+
Warning
+
Putting this JAR to another location like lib/ext WILL NOT WORK.
+
+

+ For more on that, you can also check the + Unofficial JAXP FAQ . +

+
+ +

2.7. + I get a NullPointerException, and I don't know what's wrong. +

+
+^ +
+
+

+ Often, this problem is caused by using DOM1 calls like + createElement(), setAttribute(), createAttribute(). These are + non-namespace-aware and will cause XPath and C14N errors. + Always use the DOM2 create(Attribute|Element)NS(...) + methods instead, even if you're creating an element without a namespace + (in that case, you can use null as a namespace). +

+

+ 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. +

+
+ +

2.8. + I sign a document and when I try to verify using the same key, it fails +

+
+^ +
+
+

+ After you have created the XMLSignature object, before you sign the + document, you must embed the signature element in the owning + document (using a call to XMLSignature.getElement() to + retrieve the newly created Element node from the signature) before + calling the XMLSignature.sign() method, +

+

+ During canonicalisation of the SignedInfo element, the library looks + at the parent and ancestor nodes of the Signature element to find + any namespaces that the SignedInfo node has inherited. Any that are + found are embedded in the canonical form of the SignedInfo. (This + is not true when Exclusive Canonicalisation is used, but it is still + good practice to insert the element node prior to the sign() + method being called). +

+

+ If you have not embedded the signature node in the document, it will + not have any parent or ancestor nodes, so it will not inherit their + namespaces. If you then embed it in the document and call + verify(), the namespaces will be found and the canonical + form of SignedInfo will be different to that generated during + sign(). +

+
+
+
+ +
 
+
+ + + Added: xml/site/targets/security/Java/index.html URL: http://svn.apache.org/viewvc/xml/site/targets/security/Java/index.html?view=auto&rev=498968 ============================================================================== --- xml/site/targets/security/Java/index.html (added) +++ xml/site/targets/security/Java/index.html Tue Jan 23 01:42:12 2007 @@ -0,0 +1,262 @@ + + + + + + + +The Java section + + + + + + + + +
+ +
+apache > xml.apache +
+ +
+ + + + + + + + + + + + +
+
+
+
+ +
+ + +
+ +
+ +   +
+ + + + + +
+ +

The Java section

+ + +

Version 1.4 Released

+
+

+ Version 1.4 of the Java library has been released. + The main changes for this version are: +

+
    + +
  • Implementation of the standard API JSR105
  • + +
  • Rewritten c14n that increases performance for signature + with node-set transformations.
  • + +
  • Memory footprint reduction and several bugfixes
  • + +
+

Refer to the + changelog for more information. +

+
+ + +

Overview of the Java Library

+
+

+ The Apache-XML-Security-J 1.4 supports + XML-Signature Syntax and Processing, W3C Recommendation 12 February 2002 + and + XML Encryption Syntax and Processing, W3C Recommendation 10 December 2002 + + +

+

+ As of version 1.4, the Java library supports the standard Java API + + JSR-105: XML Digital Signature APIs + for creating and validating XML Signatures. A standard Java + API for XML Encryption + + JSR-106: XML Digital Encryption APIs + is in progress and is not final, so this + API is not yet supported. You can continue to use the existing + non-standard APIs in the Java Library (there are no plans + to discontinue or deprecate them), but you should consider moving + to the standard APIs. +

+
+ + +

Old News

+
+

+ Version 1.3 released on 28 October 2005. Improves performance and + memory usage over 1.2, and includes several bugfixes. +

+

+ Version 1.2.1 released on 28 February 2005. It is a bugfix version + over 1.2 and it is recomended to upgrade to this version. +

+

+ Version 1.2 released on 11 December 2004. Improves the performance and + memory usage over 1.1 release together with an easier integration of + JCE providers. +

+

+ Version 1.1 released on 7 April 2004. Includes a beta implementation + of XML Encryption together with minor bug fixes for the XML Signature + code. +

+
+ + +

JDK 1.4 issues

+
+

+ If you use JDK 1.4 and want to use this software, be sure that Xalan is + properly installed. Check the installation guide!!! +

+

+ 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. +

+
+ +
+ +
 
+
+ + + Added: xml/site/targets/security/Java/installation.html URL: http://svn.apache.org/viewvc/xml/site/targets/security/Java/installation.html?view=auto&rev=498968 ============================================================================== --- xml/site/targets/security/Java/installation.html (added) +++ xml/site/targets/security/Java/installation.html Tue Jan 23 01:42:12 2007 @@ -0,0 +1,445 @@ + + + + + + + +Installation - Java + + + + + + + + +
+ +
+apache > xml.apache +
+ +
+ + + + + + + + + + + + +
+
+
+
+ +
+ + +
+ +
+ +   +
+ + + + + +
+ +

Installation - Java

+ + +

Using JDK 1.4.0

+
+

+ After SUN released the + + Java (TM) 2 Platform Standard Edition v1.4.0 + , the xml-security package stopped working. This is a + + known + + 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: + j2sdk1.4.0/jre/lib/endorsed/xalan.jar . 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. +

+
+
Warning
+
+ Putting this JAR to another location like lib/ext WILL + NOT WORK. +
+
+

+ For more on that, you can also check the + + Unofficial JAXP FAQ + . +

+
+ + + +

Prerequisites

+
+

+ Make sure you get the Jakarta Ant Tool from + http://jakarta.apache.org/ant/ + +

+
+ + + +

Getting the source

+
+

+ You can download the sources via WWW from the download page + at + + http://xml.apache.org/security/download.html + + +

+

+ This project's Subversion repository can be checked out anonymously + via HTTP as follows. You will need a Subversion client. +

+
svn checkout https://svn.apache.org/repos/asf/xml/security/trunk xml-security
+      
+

This will check out the code into a subdirectory named "xml-security". + The checkout will contain both the Java and the C++ source. +

+

+ A HTTP interface to browse the sources online is available via + http://svn.apache.org/viewvc/xml/security/trunk/ + +

+
+ + + +

Compiling the source

+
+

+ At the command prompt type ant test. If you want to + use jikes instead of your default java compiler locate the build.xml + file and replace the line +

+
<property name="build.compiler" value="classic"/>
+

+ with +

+
<property name="build.compiler" value="jikes"/>
+
+ + + + +

Testing the distibution

+
+

+ The first way to ensure that everything is in place is to run the unit + tests. This is simply done by typing ant test. This starts + the included JUnit test cases. Actually, we do not have complete test + coverage, but as a first start, it works. +

+
+ + + +

Playing around with the examples

+
+

+ To see how the distribution works, simply run ant + mega-sample to let ant execute several examples from the + src_samples/ directory. +

+
+ + +

Files in the source package release

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
build.xmlTop level Ant Makefile -- read README + file before building
LICENSE.txtLicense for the software
READMEBuild instructions
Readme.htmlWeb page redirect required for building documentation
STATUSCurrent source code status information
data/Directory containing sample data files and test vectors for the unit tests
doc/xml/Directory containing documentation, in XML form
src/Directory containing source code for the core library
src_samples/Directory containing source code for samples
src_unitTests/Directory containing source code for unit tests
+
+ + + +

Where is my JCE?

+
+

+ There is no 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. +

+

+ Well, how do we solve this problem? The nice guys from the Bouncy Castle 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 build.xml + and simply say ant compile or ant get-jce, + ant tries to fetch this JAR from the australian + server. After that step, the compilation works completely. +

+

+

+ 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. +

+

+

+ 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 + ./build.xml file for the properties called +

+

+
+	<property name="jce.download.file" value="jce-jdk13-124.jar />
+	<property name="jce.download" 
+	          value="http://www.bouncycastle.org/download/${jce.download.file}" />
+	<property name="lib.jce" value="${libs}/bc-${jce.download.file}" />
+	
+

+ Here you can see that the file + jce-jdk13-124.jar + is downloaded and stored in the location ./libs/bc-jce-jdk13-124.jar + +

+

+ If you do this by hand (pointing you favourite web browser and download + it yourself), simply put a "bc-" in front of the filename + and put it to ./libs/, then ant won't try to make a + download. +

+
+ +
+ +
 
+
+ + + Added: xml/site/targets/security/Java/interop.html URL: http://svn.apache.org/viewvc/xml/site/targets/security/Java/interop.html?view=auto&rev=498968 ============================================================================== --- xml/site/targets/security/Java/interop.html (added) +++ xml/site/targets/security/Java/interop.html Tue Jan 23 01:42:12 2007 @@ -0,0 +1,251 @@ + + + + + + + +Java Interoperability + + + + + + + + +
+ +
+apache > xml.apache +
+ +
+ + + + + + + + + + + + +
+
+
+
+ +
+ + +
+ +
+ +   +
+ + + + + +
+ +

Java Interoperability

+ + +

Problems

+
+

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 + + the interop matrix + ). +

+
+ + +

Interoperability issues

+
+

+ As it can be seen on the + working group homepage, + there are some interoperability reports, namely for + + Canonical XML + , + + Exclusive Canonical XML + + and + + XML Signature + . +

+

+ 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 data/ + directory. The directory includes test vectors from +

+
    + +
  • + + Baltimore KeyTools XML + +
  • + +
  • +IAIK IXSIL +
  • + +
  • + + RSA Security Cert-J + +
  • + +
  • The vectors from the + + IBM alphaWorks XML Security suite + 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 xss4j-20030127.zip from the + + alphaWorks download page + . + Copy all files from the xss4j-20030127.zip#/xss4j/data + directory into the + xml-security/data/com/ibm/xss4j-20030127/ + directory. If the + + Interop + class finds these files, the + org.apache.xml.security.test.interop.IBMTest class is + also executed during unit interop tests. +
  • + +
+
+ +
+ +
 
+
+ + + Added: xml/site/targets/security/Java/resolver.html URL: http://svn.apache.org/viewvc/xml/site/targets/security/Java/resolver.html?view=auto&rev=498968 ============================================================================== --- xml/site/targets/security/Java/resolver.html (added) +++ xml/site/targets/security/Java/resolver.html Tue Jan 23 01:42:12 2007 @@ -0,0 +1,324 @@ + + + + + + + +Resolver-Mania + + + + + + + + +
+ +
+apache > xml.apache +
+ +
+ + + + + + + + + + + + +
+
+
+
+ +
+ + +
+ +
+ +   +
+ + + + + +
+ +

Resolver-Mania

+ + +

Why do we need all these resolvers?

+
+

+ 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. +

+
+ + +

Types of resolvers

+
+ +

ResourceResolvers

+

+ A + + ResourceResolver + is used by a + + Reference + 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.
+ The concept of a + + ResourceResolver + is very similar to an org.xml.sax.EntityResolver, but in + contrast to that Interface, the ResourceResolver is able to + de-reference contents inside an XML document. +

+ +

StorageResolver

+

A + + StorageResolver + is used by + + KeyInfo + 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 + + StorageResolver + s who make requests to LDAP servers or to use specificic PKI + interfaces.
+ Bundled with the software come three sample + + StorageResolver + s which can be used for common tasks: +

+ +

+ + + StorageResolver + s are supplied to the KeyInfo's addStorageResolver() method. +

+

+ Generally, a + + StorageResolver + has only a method to return an Iterator which iterates + through the available Certificates. +

+ +

KeyResolver

+

+ A + + KeyResolver + is used by + + KeyInfo + to process it's child Elements. There exist two general + classes of a + + KeyResolver + : +

+
    + +
  • + 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. +
  • + +
  • + 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. +
  • + +
+

+ Of course, there are cross-dependencies: e.g. a KeyResolver named + + RetrievalMethodResolver + uses the + + ResourceResolver + framework to retrieve a public key or certificate from an + arbitrary location. +

+
+ +
+ +
 
+
+ + + --------------------------------------------------------------------- To unsubscribe, e-mail: general-cvs-unsubscribe@xml.apache.org For additional commands, e-mail: general-cvs-help@xml.apache.org