doc/site/src/documentation/content/xdocs/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; 
]>
<!--
Copyright 2003-2004 The Apache Software Foundation

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<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">security-dev-help@xml.apache.org</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>. 
	</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>.
	</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
	  &quot;Learn XYZ in 21 days&quot;-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>&lt;Signature&gt;</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>