docs/api/chapters/using-transforms.sgml

   1 <chapter id="xmlsec-notes-transforms">
   2     <title>Transforms and transforms chain.</title>
   3     <para>XML Digital Signature and XML Encryption standards are
   4         very flexible and provide an XML developer many different ways to
   5         sign or encrypt any part (or even parts) of an XML document.
   6         The key for such great flexibility is the "transforms" model.
   7         Transform is defined as a method of pre-processing binary or XML data
   8         before calculating digest or signature. XML Security Library extends
   9         this definition and names "transform" any operation performed on
  10         the data: reading data from an URI, xml parsing, xml transformation,
  11         calculation digest, encrypting or decrypting. Each XML Security Library
  12         transform provides at least one of the following callbacks:
  13             <itemizedlist>
  14                 <listitem><para>
  15                     <link linkend="xmlSecTransformPushBinMethod">push binary data</link>;
  16                 </para></listitem>
  17                 <listitem><para>
  18                     <link linkend="xmlSecTransformPushXmlMethod">push xml data</link>;
  19                 </para></listitem>
  20                 <listitem><para>
  21                     <link linkend="xmlSecTransformPopBinMethod">pop binary data</link>;
  22                 </para></listitem>
  23                 <listitem><para>
  24                     <link linkend="xmlSecTransformPopXmlMethod">pop xml data</link>.
  25                 </para></listitem>
  26             </itemizedlist>
  27     </para>
  28     <para>One additional <link linkend="xmlSecTransformExecuteMethod">execute</link>
  29         callback was added to simplify the development and reduce code size.
  30         This callback is used by default
  31         implementations of the four external callbacks from the list above.
  32         For example, most of the crypto transforms could be implemented by
  33         just implementing one "execute" callback and using default push/pop
  34         binary data callbacks. However, in some cases using push/pop callbacks
  35         directly is more efficient.
  36     </para>
  37     <figure>
  38         <title>The XML Security Library transform.</title>
  39         <graphic fileref="images/transform.png" align="center"></graphic>
  40     </figure>
  41     <para>XML Security Library constructs transforms chain according to the
  42         signature/encryption template or signed/encrypted document.
  43         If necessary, XML Security Library inserts XML parser or defaul
  44         canonicalization to ensure that the output data type (binary or XML)
  45         of previous transform matches the input of the next transform.
  46     </para>
  47     <para>The data are processed by pushing through or poping from the chain
  48         depending on the transforms in the chain.  For example, then binary
  49         data chunk is pushed through a binary-to-binary transform, it
  50         processes this chunk and pushes the result to the next transform
  51         in the chain.
  52     </para>
  53     <figure>
  54         <title>Transforms chain created for &lt;dsig:Reference/&gt; element processing.</title>
  55         <graphic fileref="images/transforms-chain.png" align="center"></graphic>
  56     </figure>
  57
  58     <para>
  59         <example>
  60             <title>Walking through transforms chain.</title>
  61             <programlisting><![CDATA[
  62 TODO
  63             ]]></programlisting>
  64         </example>
  65     </para>
  66 </chapter>
  67