xmlsec-shim 1.2.18.1

data/vendor/xmlsec1-1.2.18/docs/api/chapters/compiling-and-linking.sgml

@@ -0,0 +1,252 @@
+<chapter id="xmlsec-notes-compiling">
+    <title>Building the application with XML Security Library.</title>
+    <sect1 id="xmlsec-notes-compiling-overview">
+        <title>Overview.</title>
+        <para>Compiling and linking application with XML Security
+	Library requires specifying correct compilation flags, library files 
+        and paths to include and library files. As we discussed before, 
+	XML Security Library consist of the core xmlsec library and several 
+	xmlsec-crypto libraries. Application has a choice of selecting crypto 
+	library at link time or dynamicaly loading it at run time. Please note,
+	that loading crypto engines dynamicaly may introduce security problems
+	on some platforms. 
+	</para>
+    </sect1>
+    <sect1 id="xmlsec-notes-include-files" >
+	<title>Include files.</title>
+	<para>In order to use XML Security Library an application should include 
+	one or more of the following files:
+	<itemizedlist>
+	    <listitem>
+		<para><link linkend="XMLSEC-XMLSEC">xmlsec/xmlsec.h</link> -
+		XML Security Library initialization and shutdown functions;
+		</para>
+	    </listitem>
+	    <listitem>
+		<para><link linkend="XMLSEC-XMLDSIG">xmlsec/xmldsig.h</link> - 
+		XML Digital Signature functions;</para>
+	    </listitem>
+	    <listitem>
+		<para><link linkend="XMLSEC-XMLENC">xmlsec/xmlenc.h</link> - 
+		XML Encryption functions;</para>
+	    </listitem>
+	    <listitem>
+		<para><link linkend="XMLSEC-XMLTREE">xmlsec/xmltree.h</link> -
+		helper functions for XML documents manipulation;
+		</para>
+	    </listitem>
+	    <listitem>
+		<para><link linkend="XMLSEC-TEMPLATES">xmlsec/templates.h</link> -
+		helper functions for dynamic XML Digital Signature and 
+		XML Encryption templates creation;
+		</para>
+	    </listitem>
+	    <listitem>
+		<para><link linkend="XMLSEC-CRYPTO">xmlsec/crypto.h</link> -
+		automatic XML Security Crypto Library selection.
+		</para>
+	    </listitem>
+	</itemizedlist>
+	</para>
+	<para>If necessary, the application should also include LibXML, 
+	LibXSLT and crypto library header files.
+	</para>
+	<para>
+	<example>
+	    <title>Example includes file section.</title>
+	    <programlisting><![CDATA[
+#include <libxml/tree.h>
+#include <libxml/xmlmemory.h>
+#include <libxml/parser.h>
+
+#ifndef XMLSEC_NO_XSLT
+#include <libxslt/xslt.h>
+#endif /* XMLSEC_NO_XSLT */
+
+#include <xmlsec/xmlsec.h>
+#include <xmlsec/xmltree.h>
+#include <xmlsec/xmldsig.h>
+#include <xmlsec/xmlenc.h>
+#include <xmlsec/templates.h>
+#include <xmlsec/crypto.h>
+	    ]]></programlisting>
+	</example>
+	</para>
+    </sect1>
+    <sect1 id="xmlsec-notes-compiling-unix" >
+	<title>Compiling and linking on Unix.</title>
+	<para>There are several ways to get necessary compilation
+	and linking information on Unix and application can use
+	any of these methods to do crypto engine selection either
+	at linking or run time.
+	
+	<itemizedlist>
+	    <listitem><para>PKG_CHECK_MODULES() macro
+		<example>
+		    <title>Using PKG_CHECK_MODULES() macro in a configure.in file
+		    to select crypto engine (openssl) at linking time.</title>
+		    <programlisting><![CDATA[
+dnl 
+dnl Check for xmlsec and friends
+dnl
+PKG_CHECK_MODULES(XMLSEC, xmlsec1-openssl >= 1.0.0 xml2 libxslt,,exit)
+CFLAGS="$CFLAGS $XMLSEC_CFLAGS"
+CPPFLAGS="$CPPFLAGS $XMLSEC_CFLAGS"
+LDFLAGS="$LDFLAGS $XMLSEC_LIBS"
+		    ]]></programlisting>
+		</example>
+
+		<example>
+		    <title>Using PKG_CHECK_MODULES() macro in a configure.in file
+		    to enable dynamical loading of xmlsec-crypto library.</title>
+		    <programlisting><![CDATA[
+dnl 
+dnl Check for xmlsec and friends
+dnl
+PKG_CHECK_MODULES(XMLSEC, xmlsec1 >= 1.0.0 xml2 libxslt,,exit)
+CFLAGS="$CFLAGS $XMLSEC_CFLAGS"
+CPPFLAGS="$CPPFLAGS $XMLSEC_CFLAGS"
+LDFLAGS="$LDFLAGS $XMLSEC_LIBS"
+		    ]]></programlisting>
+		</example>
+
+	    </para></listitem>
+
+
+	    <listitem><para>pkg-config script
+		<example>
+		    <title>Using pkg-config script in a Makefile
+		    to select crypto engine (nss) at linking time.</title>
+		    <programlisting><![CDATA[
+PROGRAM = test
+PROGRAM_FILES = test.c
+
+CFLAGS	+= -g $(shell pkg-config --cflags xmlsec1-nss)
+LDFLAGS	+= -g
+LIBS 	+= $(shell pkg-config --libs xmlsec1-nss) 
+
+all: $(PROGRAM)
+
+%: %.c 
+	$(cc) $(PROGRAM_FILES) $(CFLAGS) $(LDFLAGS) -o $(PROGRAM) $(LIBS)
+
+clean:
+	@rm -rf $(PROGRAM)
+		    ]]></programlisting>
+		</example>
+
+
+		<example>
+		    <title>Using pkg-config script in a Makefile
+		    to enable dynamical loading of xmlsec-crypto library.</title>
+		    <programlisting><![CDATA[
+PROGRAM = test
+PROGRAM_FILES = test.c
+
+CFLAGS	+= -g $(shell pkg-config --cflags xmlsec1)
+LDFLAGS	+= -g
+LIBS 	+= $(shell pkg-config --libs xmlsec1) 
+
+all: $(PROGRAM)
+
+%: %.c 
+	$(cc) $(PROGRAM_FILES) $(CFLAGS) $(LDFLAGS) -o $(PROGRAM) $(LIBS)
+
+clean:
+	@rm -rf $(PROGRAM)
+		    ]]></programlisting>
+		</example>
+
+	    </para></listitem>
+	    <listitem><para>xmlsec1-config script
+		<example>
+		    <title>Using xmlsec1-config script in a Makefile
+		    to select crypto engine (e.g. gnutls) at linking time.</title>
+		    <programlisting><![CDATA[
+PROGRAM = test
+PROGRAM_FILES = test.c
+
+CFLAGS	+= -g $(shell xmlsec1-config --crypto gnutls --cflags)
+LDFLAGS	+= -g
+LIBS 	+= $(shell xmlsec1-config --crypto gnutls --libs) 
+
+all: $(PROGRAM)
+
+%: %.c 
+	$(cc) $(PROGRAM_FILES) $(CFLAGS) $(LDFLAGS) -o $(PROGRAM) $(LIBS)
+
+clean:
+	@rm -rf $(PROGRAM)
+		    ]]></programlisting>
+		</example>
+
+		<example>
+		    <title>Using xmlsec1-config script in a Makefile
+		    to enable dynamical loading of xmlsec-crypto library.</title>
+		    <programlisting><![CDATA[
+PROGRAM = test
+PROGRAM_FILES = test.c
+
+CFLAGS	+= -g $(shell xmlsec1-config --cflags)
+LDFLAGS	+= -g
+LIBS 	+= $(shell xmlsec1-config --libs) 
+
+all: $(PROGRAM)
+
+%: %.c 
+	$(cc) $(PROGRAM_FILES) $(CFLAGS) $(LDFLAGS) -o $(PROGRAM) $(LIBS)
+
+clean:
+	@rm -rf $(PROGRAM)
+		    ]]></programlisting>
+		</example>
+		</para></listitem>
+	</itemizedlist>
+	</para>
+    </sect1>
+    <sect1 id="xmlsec-notes-compiling-windows" >
+	<title>Compiling and linking on Windows.</title>
+	<para>On Windows there is no such simple and elegant solution.
+	Please check <filename>README</filename> file in <filename>win32</filename>
+	folder of the library package for latest instructions.
+	However, there are few general things, that you need to remember:
+	<itemizedlist>
+	    <listitem><para>	
+	     <emphasis>All libraries linked to your application must be compiled
+	    with the same Microsoft Runtime Libraries.</emphasis>
+	    </para></listitem>
+	    <listitem><para>	
+	     <emphasis>Static linking with XML Security Library requires 
+	     additional global defines:</emphasis>
+	      <informalexample><programlisting>
+#define LIBXML_STATIC
+#define LIBXSLT_STATIC
+#define XMLSEC_STATIC	    
+	     </programlisting></informalexample>
+	    </para></listitem>
+	    <listitem><para>
+	    If you do not want to dynamicaly load xmlsec-crypto library
+	    and prefer to select crypto engine at linking then you should
+	    link your application with xmlsec and at least one of 
+	    xmlsec-crypto libraries.
+	    </para></listitem>
+	    <listitem><para>
+	    In order to enable dynamic loading for xmlsec-crypto library
+	    you should add additional global define:
+	      <informalexample><programlisting>
+#define XMLSEC_CRYPTO_DYNAMIC_LOADING
+	     </programlisting></informalexample>	    
+	    </para></listitem>
+	</itemizedlist>
+	</para>
+    </sect1>
+    <sect1 id="xmlsec-notes-compiling-others">
+	<title>Compiling and linking on other systems.</title>
+	<para>Well, nothing is impossible, it's only software (you managed to 
+	compile the library itself, do you?). 
+	I'll be happy to include in this manual your expirience with
+	compiling and linking applications with XML Security Library
+	on other platforms (if you would like to share it).
+	</para>
+    </sect1>
+</chapter>

data/vendor/xmlsec1-1.2.18/docs/api/chapters/creating-templates.sgml

@@ -0,0 +1,325 @@
+<chapter id="xmlsec-notes-templates">
+    <title>Creating dynamic templates.</title>
+    <sect1 id="xmlsec-notes-templates-overview">
+        <title>Overview.</title>
+	<para>The XML Security Library uses templates to describe
+        how and what data should be signed or encrypted. The template
+        is a regular XML file. You can create templates in advance
+        using your favorite XML files editor, load them from a file
+        and use for creating signature or encrypting data. You can 
+        also create templates dynamicaly. The XML Security Library
+        provides helper functions to quickly create dynamic templates
+        inside your application.</para>
+    </sect1>
+    <sect1 id="xmlsec-notes-dynamic-signature-templates">
+	<title>Creating dynamic signature templates.</title>
+	<para>The signature template has structure similar 
+	to the XML Digital Signature structure as it is described in 
+	<ulink URL="http://www.w3.org/TR/xmldsig-core">specification</ulink>.
+	The only difference is that some nodes (for example,
+	&lt;dsig:DigestValue/&gt; or &lt;SignatureValue/&gt;)
+	are empty. The XML Security Library sets the content of these
+	nodes after doing necessary calculations.
+	</para>
+	<figure>
+	    <title>XML Digital Signature structure</title>
+	    <programlisting>
+&lt;dsig:Signature ID?&gt; 
+    &lt;dsig:SignedInfo&gt;
+        &lt;dsig:CanonicalizationMethod Algorithm /&gt;
+        &lt;dsig:SignatureMethod Algorithm /&gt;
+        (&lt;dsig:Reference URI? &gt;
+    	    (&lt;dsig:Transforms&gt;
+		(&lt;dsig:Transform Algorithm /&gt;)+
+	     &lt;/dsig:Transforms&gt;)?
+	    &lt;dsig:DigestMethod Algorithm &gt;
+	    &lt;dsig:DigestValue&gt;
+	&lt;/dsig:Reference&gt;)+
+    &lt;/dsig:SignedInfo&gt;
+    &lt;dsig:SignatureValue&gt; 
+    (&lt;dsig:KeyInfo&gt;
+	&lt;dsig:KeyName&gt;?
+	&lt;dsig:KeyValue&gt;?
+	&lt;dsig:RetrievalMethod&gt;?
+	&lt;dsig:X509Data&gt;?
+	&lt;dsig:PGPData&gt;?
+	&lt;enc:EncryptedKey&gt;?
+	&lt;enc:AgreementMethod&gt;?
+	&lt;dsig:KeyName&gt;?
+	&lt;dsig:RetrievalMethod&gt;?
+	&lt;*&gt;?
+    &lt;/dsig:KeyInfo&gt;)?
+    (&lt;dsig:Object ID?&gt;)*
+&lt;/dsig:Signature&gt;
+	    </programlisting>
+	</figure>
+	<para>
+	     <example>
+		<title>Creating dynamic signature template.</title>
+		<programlisting><![CDATA[
+/** 
+ * sign_file:
+ * @xml_file:		the XML file name.
+ * @key_file:		the PEM private key file name.
+ *
+ * Signs the #xml_file using private key from #key_file and dynamicaly
+ * created enveloped signature template.
+ *
+ * Returns 0 on success or a negative value if an error occurs.
+ */
+int 
+sign_file(const char* xml_file, const char* key_file) {
+    xmlDocPtr doc = NULL;
+    xmlNodePtr signNode = NULL;
+    xmlNodePtr refNode = NULL;
+    xmlNodePtr keyInfoNode = NULL;
+    xmlSecDSigCtxPtr dsigCtx = NULL;
+    int res = -1;
+    
+    assert(xml_file);
+    assert(key_file);
+
+    /* load doc file */
+    doc = xmlParseFile(xml_file);
+    if ((doc == NULL) || (xmlDocGetRootElement(doc) == NULL)){
+	fprintf(stderr, "Error: unable to parse file \"%s\"\n", xml_file);
+	goto done;	
+    }
+    
+    /* create signature template for RSA-SHA1 enveloped signature */
+    signNode = xmlSecTmplSignatureCreate(doc, xmlSecTransformExclC14NId,
+				         xmlSecTransformRsaSha1Id, NULL);
+    if(signNode == NULL) {
+	fprintf(stderr, "Error: failed to create signature template\n");
+	goto done;		
+    }
+
+    /* add <dsig:Signature/> node to the doc */
+    xmlAddChild(xmlDocGetRootElement(doc), signNode);
+    
+    /* add reference */
+    refNode = xmlSecTmplSignatureAddReference(signNode, xmlSecTransformSha1Id,
+					NULL, NULL, NULL);
+    if(refNode == NULL) {
+	fprintf(stderr, "Error: failed to add reference to signature template\n");
+	goto done;		
+    }
+
+    /* add enveloped transform */
+    if(xmlSecTmplReferenceAddTransform(refNode, xmlSecTransformEnvelopedId) == NULL) {
+	fprintf(stderr, "Error: failed to add enveloped transform to reference\n");
+	goto done;		
+    }
+
+    /* add <dsig:KeyInfo/> and <dsig:KeyName/> nodes to put key name in the signed document */
+    keyInfoNode = xmlSecTmplSignatureEnsureKeyInfo(signNode, NULL);
+    if(keyInfoNode == NULL) {
+	fprintf(stderr, "Error: failed to add key info\n");
+	goto done;		
+    }
+
+    if(xmlSecTmplKeyInfoAddKeyName(keyInfoNode, NULL) == NULL) {
+	fprintf(stderr, "Error: failed to add key name\n");
+	goto done;		
+    }
+
+    /* create signature context, we don't need keys manager in this example */
+    dsigCtx = xmlSecDSigCtxCreate(NULL);
+    if(dsigCtx == NULL) {
+        fprintf(stderr,"Error: failed to create signature context\n");
+	goto done;
+    }
+
+    /* load private key, assuming that there is not password */
+    dsigCtx->signKey = xmlSecCryptoAppKeyLoad(key_file, xmlSecKeyDataFormatPem, NULL, NULL, NULL);
+    if(dsigCtx->signKey == NULL) {
+        fprintf(stderr,"Error: failed to load private pem key from \"%s\"\n", key_file);
+	goto done;
+    }
+
+    /* set key name to the file name, this is just an example! */
+    if(xmlSecKeySetName(dsigCtx->signKey, key_file) < 0) {
+    	fprintf(stderr,"Error: failed to set key name for key from \"%s\"\n", key_file);
+	goto done;
+    }
+
+    /* sign the template */
+    if(xmlSecDSigCtxSign(dsigCtx, signNode) < 0) {
+        fprintf(stderr,"Error: signature failed\n");
+	goto done;
+    }
+        
+    /* print signed document to stdout */
+    xmlDocDump(stdout, doc);
+    
+    /* success */
+    res = 0;
+
+done:    
+    /* cleanup */
+    if(dsigCtx != NULL) {
+	xmlSecDSigCtxDestroy(dsigCtx);
+    }
+    
+    if(doc != NULL) {
+	xmlFreeDoc(doc); 
+    }
+    return(res);
+}
+		]]></programlisting>
+		<simpara><link linkend="xmlsec-example-sign2">Full program listing</link></simpara>
+	    </example>
+	</para>
+    </sect1>
+        
+    <sect1 id="xmlsec-notes-dynamic-encryption-templates">
+	<title>Creating dynamic encryption templates.</title>
+	<para>The encryption template has structure similar 
+	to the XML Encryption structure as it is described in 
+	<ulink URL="http://www.w3.org/TR/xmlenc-core">specification</ulink>.
+	The only difference is that some nodes (for example,
+	&lt;enc:CipherValue/&gt;)
+	are empty. The XML Security Library sets the content of these
+	nodes after doing necessary calculations.
+	</para>
+	<figure>
+	    <title>XML Encryption structure</title>
+	    <programlisting>
+&lt;enc:EncryptedData Id? Type? MimeType? Encoding?&gt;
+    &lt;enc:EncryptionMethod Algorithm /&gt;?
+    (&lt;dsig:KeyInfo&gt;
+	&lt;dsig:KeyName&gt;?
+	&lt;dsig:KeyValue&gt;?
+	&lt;dsig:RetrievalMethod&gt;?
+	&lt;dsig:X509Data&gt;?
+	&lt;dsig:PGPData&gt;?
+	&lt;enc:EncryptedKey&gt;?
+	&lt;enc:AgreementMethod&gt;?
+	&lt;dsig:KeyName&gt;?
+	&lt;dsig:RetrievalMethod&gt;?
+	&lt;*&gt;?
+    &lt;/dsig:KeyInfo&gt;)?
+    &lt;enc:CipherData&gt;
+	&lt;enc:CipherValue&gt;?
+	&lt;enc:CipherReference URI?&gt;?
+    &lt;/enc:CipherData&gt;
+    &lt;enc:EncryptionProperties&gt;?
+&lt;/enc:EncryptedData&gt;	
+	    </programlisting>
+	</figure>
+	<para>
+	     <example>
+		<title>Creating dynamic encrytion template.</title>
+		<programlisting><![CDATA[
+/**
+ * encrypt_file:
+ * @xml_file:		the encryption template file name.
+ * @key_file:		the Triple DES key file.
+ *
+ * Encrypts #xml_file using a dynamicaly created template and DES key from
+ * #key_file.
+ *
+ * Returns 0 on success or a negative value if an error occurs.
+ */
+int 
+encrypt_file(const char* xml_file, const char* key_file) {
+    xmlDocPtr doc = NULL;
+    xmlNodePtr encDataNode = NULL;
+    xmlNodePtr keyInfoNode = NULL;
+    xmlSecEncCtxPtr encCtx = NULL;
+    int res = -1;
+    
+    assert(xml_file);
+    assert(key_file);
+
+    /* load template */
+    doc = xmlParseFile(xml_file);
+    if ((doc == NULL) || (xmlDocGetRootElement(doc) == NULL)){
+	fprintf(stderr, "Error: unable to parse file \"%s\"\n", xml_file);
+	goto done;	
+    }
+    
+    /* create encryption template to encrypt XML file and replace 
+     * its content with encryption result */
+    encDataNode = xmlSecTmplEncDataCreate(doc, xmlSecTransformDes3CbcId,
+				NULL, xmlSecTypeEncElement, NULL, NULL);
+    if(encDataNode == NULL) {
+	fprintf(stderr, "Error: failed to create encryption template\n");
+	goto done;   
+    }
+
+    /* we want to put encrypted data in the <enc:CipherValue/> node */
+    if(xmlSecTmplEncDataEnsureCipherValue(encDataNode) == NULL) {
+	fprintf(stderr, "Error: failed to add CipherValue node\n");
+	goto done;   
+    }
+
+    /* add <dsig:KeyInfo/> and <dsig:KeyName/> nodes to put key name in the signed document */
+    keyInfoNode = xmlSecTmplEncDataEnsureKeyInfo(encDataNode, NULL);
+    if(keyInfoNode == NULL) {
+	fprintf(stderr, "Error: failed to add key info\n");
+	goto done;		
+    }
+
+    if(xmlSecTmplKeyInfoAddKeyName(keyInfoNode, NULL) == NULL) {
+	fprintf(stderr, "Error: failed to add key name\n");
+	goto done;		
+    }
+
+    /* create encryption context, we don't need keys manager in this example */
+    encCtx = xmlSecEncCtxCreate(NULL);
+    if(encCtx == NULL) {
+        fprintf(stderr,"Error: failed to create encryption context\n");
+	goto done;
+    }
+
+    /* load DES key, assuming that there is not password */
+    encCtx->encKey = xmlSecKeyReadBinaryFile(xmlSecKeyDataDesId, key_file);
+    if(encCtx->encKey == NULL) {
+        fprintf(stderr,"Error: failed to load des key from binary file \"%s\"\n", key_file);
+	goto done;
+    }
+
+    /* set key name to the file name, this is just an example! */
+    if(xmlSecKeySetName(encCtx->encKey, key_file) < 0) {
+    	fprintf(stderr,"Error: failed to set key name for key from \"%s\"\n", key_file);
+	goto done;
+    }
+
+    /* encrypt the data */
+    if(xmlSecEncCtxXmlEncrypt(encCtx, encDataNode, xmlDocGetRootElement(doc)) < 0) {
+        fprintf(stderr,"Error: encryption failed\n");
+	goto done;
+    }
+    
+    /* we template is inserted in the doc */
+    encDataNode = NULL;
+        
+    /* print encrypted data with document to stdout */
+    xmlDocDump(stdout, doc);
+    
+    /* success */
+    res = 0;
+
+done:    
+
+    /* cleanup */
+    if(encCtx != NULL) {
+	xmlSecEncCtxDestroy(encCtx);
+    }
+
+    if(encDataNode != NULL) {
+	xmlFreeNode(encDataNode);
+    }
+        
+    if(doc != NULL) {
+	xmlFreeDoc(doc); 
+    }
+    return(res);
+}
+		]]></programlisting>
+		<simpara><link linkend="xmlsec-example-encrypt2">Full program listing</link></simpara>
+	    </example>
+	</para>
+    </sect1>
+</chapter>