diff options
Diffstat (limited to 'docs/api/chapters/using-transforms.sgml')
| -rw-r--r-- | docs/api/chapters/using-transforms.sgml | 67 |
1 files changed, 67 insertions, 0 deletions
diff --git a/docs/api/chapters/using-transforms.sgml b/docs/api/chapters/using-transforms.sgml new file mode 100644 index 00000000..874f41ca --- /dev/null +++ b/docs/api/chapters/using-transforms.sgml @@ -0,0 +1,67 @@ +<chapter id="xmlsec-notes-transforms"> + <title>Transforms and transforms chain.</title> + <para>XML Digital Signature and XML Encryption standards are + very flexible and provide an XML developer many different ways to + sign or encrypt any part (or even parts) of an XML document. + The key for such great flexibility is the "transforms" model. + Transform is defined as a method of pre-processing binary or XML data + before calculating digest or signature. XML Security Library extends + this definition and names "transform" any operation performed on + the data: reading data from an URI, xml parsing, xml transformation, + calculation digest, encrypting or decrypting. Each XML Security Library + transform provides at least one of the following callbacks: + <itemizedlist> + <listitem><para> + <link linkend="xmlSecTransformPushBinMethod">push binary data</link>; + </para></listitem> + <listitem><para> + <link linkend="xmlSecTransformPushXmlMethod">push xml data</link>; + </para></listitem> + <listitem><para> + <link linkend="xmlSecTransformPopBinMethod">pop binary data</link>; + </para></listitem> + <listitem><para> + <link linkend="xmlSecTransformPopXmlMethod">pop xml data</link>. + </para></listitem> + </itemizedlist> + </para> + <para>One additional <link linkend="xmlSecTransformExecuteMethod">execute</link> + callback was added to simplify the development and reduce code size. + This callback is used by default + implementations of the four external callbacks from the list above. + For example, most of the crypto transforms could be implemented by + just implementing one "execute" callback and using default push/pop + binary data callbacks. However, in some cases using push/pop callbacks + directly is more efficient. + </para> + <figure> + <title>The XML Security Library transform.</title> + <graphic fileref="images/transform.png" align="center"></graphic> + </figure> + <para>XML Security Library constructs transforms chain according to the + signature/encryption template or signed/encrypted document. + If necessary, XML Security Library inserts XML parser or defaul + canonicalization to ensure that the output data type (binary or XML) + of previous transform matches the input of the next transform. + </para> + <para>The data are processed by pushing through or poping from the chain + depending on the transforms in the chain. For example, then binary + data chunk is pushed through a binary-to-binary transform, it + processes this chunk and pushes the result to the next transform + in the chain. + </para> + <figure> + <title>Transforms chain created for <dsig:Reference/> element processing.</title> + <graphic fileref="images/transforms-chain.png" align="center"></graphic> + </figure> + + <para> + <example> + <title>Walking through transforms chain.</title> + <programlisting><![CDATA[ +TODO + ]]></programlisting> + </example> + </para> +</chapter> + |