xmlsec-shim 1.2.18.1

data/vendor/xmlsec1-1.2.18/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 &lt;dsig:Reference/&gt; 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>
+

data/vendor/xmlsec1-1.2.18/docs/api/chapters/using-x509-certs.sgml

@@ -0,0 +1,197 @@
+<chapter id="xmlsec-notes-x509">
+    <title>Using X509 Certificates.</title>
+    <sect1 id="xmlsec-notes-x509-overview">
+        <title>Overview.</title>
+        <para>X509 certificate is one of many possible keys data object that can be
+        associated with a key. Application may read and write X509 data
+	from/to XML file. The X509 certificates management policies significantly
+        vary from one crypto library to another. The examples in this chapter
+        were tested with OpenSSL and they might be broken if anither crypto
+	engine is used. Check API reference documentation for more specific 
+        information about your crypto engine.
+	</para>
+    </sect1>
+    
+    <sect1 id="xmlsec-notes-sign-x509" >
+	<title>Signing data with X509 certificate.</title>
+	<para>To sign a file using X509 certificate, 
+	an application need to associate the certificate (or certificates) 
+	with the private key using one of the following functions:
+	<itemizedlist>
+	    <listitem><para>
+	    <link linkend="xmlSecOpenSSLAppKeyCertLoad">xmlSecOpenSSLAppKeyCertLoad</link> - loads
+	    certificate from a file and adds to the key;
+	    </para></listitem>
+
+	    <listitem><para>
+	    <link linkend="xmlSecOpenSSLAppPkcs12Load">xmlSecOpenSSLAppPkcs12Load</link> -
+	    loads private key and all the certificates associated with it from a PKCS12 file;
+	    </para></listitem>
+
+	    <listitem><para>
+	    <link linkend="xmlSecKeyAdoptData">xmlSecKeyAdoptData</link> - low level
+	    function to add key data (including X509 key data) to the key.
+	    </para></listitem>
+	</itemizedlist>	    
+	<example>
+	    <title>Loading private key and X509 certificate.</title>
+	    <programlisting><![CDATA[
+    /* load private key, assuming that there is not password */
+    key = xmlSecCryptoAppKeyLoad(key_file, xmlSecKeyDataFormatPem, NULL, NULL, NULL);
+    if(key == NULL) {
+        fprintf(stderr,"Error: failed to load private pem key from \"%s\"\n", key_file);
+	goto done;
+    }
+    
+    /* load certificate and add to the key */
+    if(xmlSecCryptoAppKeyCertLoad(key, cert_file, xmlSecKeyDataFormatPem) < 0) {
+        fprintf(stderr,"Error: failed to load pem certificate \"%s\"\n", cert_file);
+	goto done;
+    }
+	    ]]></programlisting>
+	    <simpara><link linkend="xmlsec-example-sign3">Full program listing</link></simpara>
+	</example>
+	</para>
+	<para>Next step is to prepare signature template with &lt;dsig:X509Data/&gt;
+	child of the &lt;dsig:KeyInfo/&gt; element. When XML Security Library finds
+	this node in the template, it automaticaly creates &lt;dsig:X509Certificate/&gt; 
+	children of the &lt;dsig:X509Data/&gt; element and writes to result XML document
+	all the certificates associated with the signature key. 
+	<example>
+	    <title>Dynamicaly creating a signature template for signing document using X509 certificate.</title>
+	    <programlisting><![CDATA[
+    /* 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:X509Data/> */
+    keyInfoNode = xmlSecTmplSignatureEnsureKeyInfo(signNode, NULL);
+    if(keyInfoNode == NULL) {
+	fprintf(stderr, "Error: failed to add key info\n");
+	goto done;		
+    }
+    
+    if(xmlSecTmplKeyInfoAddX509Data(keyInfoNode) == NULL) {
+	fprintf(stderr, "Error: failed to add X509Data node\n");
+	goto done;		
+    }
+	    ]]></programlisting>
+	    <simpara><link linkend="xmlsec-example-sign3">Full program listing</link></simpara>
+	</example>
+	</para>
+    </sect1>
+
+    <sect1 id="xmlsec-notes-verify-x509" >
+	<title>Verifing document signed with X509 certificates.</title>
+	<para>
+	If the document is signed with an X509 certificate then the signature
+	verification consist of two steps:
+	<itemizedlist>
+	    <listitem><para>Creating and verifing X509 certificates chain.
+	    </para></listitem>
+	    <listitem><para>Verifing signature itself using key exrtacted from 
+	    a certificate verified on previous step.
+	    </para></listitem>
+	</itemizedlist>
+	Certificates chain is constructed from certificates in a way that
+	each certificate in the chain is signed with previous one:
+	<figure>
+	    <title>Certificates chain.</title>
+	    <programlisting>
+Certificate A (signed with B) <- Certificate B (signed with C) <- ... <- Root Certificate (signed by itself)
+	    </programlisting>
+	</figure>
+	At the end of the chain there is a &quot;Root Certificate&quot; which
+	is signed by itself. There is no way to verify the validity of the
+	root certificate and application have to &quot;trust&quot; it
+	(another name for root certificates is &quot;trusted&quot; certificates).
+	</para>
+	
+	<para>
+	Application can use <link linkend="xmlSecCryptoAppKeysMngrCertLoad">xmlSecCryptoAppKeysMngrCertLoad</link>
+	function to load both &quot;trusted&quot; and &quot;un-trusted&quot;
+	certificates. However, the selection of &quot;trusted&quot;
+	certificates is very sensitive process and this function might be
+	not implemented for some crypto engines. In this case, the 
+	&quot;trusted&quot; certificates list is loaded during initialization
+	or specified in crypto engine configuration files.
+	Check XML Security Library API reference for more details. 
+	<example>
+	    <title>Loading trusted X509 certificate.</title>
+	    <programlisting><![CDATA[
+/**
+ * load_trusted_certs:
+ * @files:		the list of filenames.
+ * @files_size:		the number of filenames in #files.
+ *
+ * Creates simple keys manager and load trusted certificates from PEM #files.
+ * The caller is responsible for destroing returned keys manager using
+ * @xmlSecKeysMngrDestroy.
+ *
+ * Returns the pointer to newly created keys manager or NULL if an error
+ * occurs.
+ */
+xmlSecKeysMngrPtr 
+load_trusted_certs(char** files, int files_size) {
+    xmlSecKeysMngrPtr mngr;
+    int i;
+        
+    assert(files);
+    assert(files_size > 0);
+    
+    /* create and initialize keys manager, we use a simple list based
+     * keys manager, implement your own xmlSecKeysStore klass if you need
+     * something more sophisticated 
+     */
+    mngr = xmlSecKeysMngrCreate();
+    if(mngr == NULL) {
+	fprintf(stderr, "Error: failed to create keys manager.\n");
+	return(NULL);
+    }
+    if(xmlSecCryptoAppDefaultKeysMngrInit(mngr) < 0) {
+	fprintf(stderr, "Error: failed to initialize keys manager.\n");
+	xmlSecKeysMngrDestroy(mngr);
+	return(NULL);
+    }    
+    
+    for(i = 0; i < files_size; ++i) {
+	assert(files[i]);
+
+	/* load trusted cert */
+	if(xmlSecCryptoAppKeysMngrCertLoad(mngr, files[i], xmlSecKeyDataFormatPem, xmlSecKeyDataTypeTrusted) < 0) {
+    	    fprintf(stderr,"Error: failed to load pem certificate from \"%s\"\n", files[i]);
+	    xmlSecKeysMngrDestroy(mngr);
+	    return(NULL);
+	}
+    }
+
+    return(mngr);
+}
+	    ]]></programlisting>
+	    <simpara><link linkend="xmlsec-example-verify3">Full program listing</link></simpara>
+	</example>
+	</para>
+    </sect1>
+</chapter>
+

data/vendor/xmlsec1-1.2.18/docs/api/chapters/verify-and-decrypt.sgml

@@ -0,0 +1,265 @@
+<chapter id="xmlsec-notes-verify-decrypt">
+    <title>Verifing and decrypting documents.</title>
+    <sect1 id="xmlsec-notes-verify-decrypt-overview">
+        <title>Overview.</title>
+        <para>Since the template is just an XML file, it might be created in advance 
+	and saved in a file. It's also possible for application to create 
+	templates without using XML Security Library functions. Also in some 
+	cases template should be inserted in the signed or encrypted data 
+	(for example, if you want to create an enveloped or enveloping 
+	signature).</para>
+	<para>Signature verification and data decryption do not require template 
+	because all the necessary information is provided in the signed or 
+	encrypted document.
+    	  <figure>
+	    <title>The verification or decryption processing model.</title>
+	    <graphic fileref="images/verif-dec-model.png" align="center"></graphic>
+	  </figure>	 
+	</para>
+    </sect1>
+    
+    <sect1 id="xmlsec-notes-verify" >
+	<title>Verifying a signed document</title>
+	<para>The typical siganture verification process includes following steps:
+	  <itemizedlist>
+	    <listitem><para>
+		Load keys, X509 certificates, etc. in the <link linkend="xmlSecKeysMngr">keys manager</link> .
+	    </para></listitem>
+	    <listitem><para>
+		Create signature context <link linkend="xmlSecDSigCtx">xmlSecDSigCtx</link>
+		using <link linkend="xmlSecDSigCtxCreate">xmlSecDSigCtxCreate</link> or
+		<link linkend="xmlSecDSigCtxInitialize">xmlSecDSigCtxInitialize</link>
+		functions.
+	    </para></listitem>
+	    <listitem><para>
+		Select start verification 
+    		<ulink URL="http://www.w3.org/TR/xmldsig-core/#sec-Signature">&lt;dsig:Signature/&gt;</ulink>
+		node in the signed XML document.
+	    </para></listitem>
+	    <listitem><para>
+		Verify signature by calling <link linkend="xmlSecDSigCtxVerify">xmlSecDSigCtxVerify</link> 
+		function.
+	    </para></listitem>
+	    <listitem><para>
+		Check returned value and verification status (<structfield>status</structfield>
+		member of <link linkend="xmlSecDSigCtx">xmlSecDSigCtx</link> structure).
+		If necessary, consume returned data from the <link linkend="xmlSecDSigCtx">context</link>.
+	    </para></listitem>
+	    <listitem><para>
+		Destroy signature context <link linkend="xmlSecDSigCtx">xmlSecDSigCtx</link>
+		using <link linkend="xmlSecDSigCtxDestroy">xmlSecDSigCtxDestroy</link> or
+		<link linkend="xmlSecDSigCtxFinalize">xmlSecDSigCtxFinalize</link>
+		functions.
+	    </para></listitem>
+	  </itemizedlist>
+	</para>
+	<para>
+	     <example>
+		<title>Verifying a document.</title>
+		<programlisting><![CDATA[
+/** 
+ * verify_file:
+ * @xml_file:		the signed XML file name.
+ * @key_file:		the PEM public key file name.
+ *
+ * Verifies XML signature in #xml_file using public key from #key_file.
+ *
+ * Returns 0 on success or a negative value if an error occurs.
+ */
+int 
+verify_file(const char* xml_file, const char* key_file) {
+    xmlDocPtr doc = NULL;
+    xmlNodePtr node = NULL;
+    xmlSecDSigCtxPtr dsigCtx = NULL;
+    int res = -1;
+    
+    assert(xml_file);
+    assert(key_file);
+
+    /* load file */
+    doc = xmlParseFile(xml_file);
+    if ((doc == NULL) || (xmlDocGetRootElement(doc) == NULL)){
+	fprintf(stderr, "Error: unable to parse file \"%s\"\n", xml_file);
+	goto done;	
+    }
+    
+    /* find start node */
+    node = xmlSecFindNode(xmlDocGetRootElement(doc), xmlSecNodeSignature, xmlSecDSigNs);
+    if(node == NULL) {
+	fprintf(stderr, "Error: start node not found in \"%s\"\n", xml_file);
+	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 public key */
+    dsigCtx->signKey = xmlSecCryptoAppKeyLoad(key_file,xmlSecKeyDataFormatPem, NULL, NULL, NULL);
+    if(dsigCtx->signKey == NULL) {
+        fprintf(stderr,"Error: failed to load public 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;
+    }
+
+    /* Verify signature */
+    if(xmlSecDSigCtxVerify(dsigCtx, node) < 0) {
+        fprintf(stderr,"Error: signature verify\n");
+	goto done;
+    }
+        
+    /* print verification result to stdout */
+    if(dsigCtx->status == xmlSecDSigStatusSucceeded) {
+	fprintf(stdout, "Signature is OK\n");
+    } else {
+	fprintf(stdout, "Signature is INVALID\n");
+    }    
+
+    /* success */
+    res = 0;
+
+done:    
+    /* cleanup */
+    if(dsigCtx != NULL) {
+	xmlSecDSigCtxDestroy(dsigCtx);
+    }
+    
+    if(doc != NULL) {
+	xmlFreeDoc(doc); 
+    }
+    return(res);
+}
+		]]></programlisting>
+	    <simpara><link linkend="xmlsec-example-verify1">Full Program Listing</link></simpara>
+	    </example>
+	</para>
+    </sect1>
+
+    <sect1 id="xmlsec-notes-decrypt" >
+	<title>Decrypting an encrypted document</title>
+	<para>The typical decryption process includes following steps:
+	  <itemizedlist>
+	    <listitem><para>
+		Load keys, X509 certificates, etc. in the <link linkend="xmlSecKeysMngr">keys manager</link> .
+	    </para></listitem>
+	    <listitem><para>
+		Create encryption context <link linkend="xmlSecEncCtx">xmlSecEncCtx</link>
+		using <link linkend="xmlSecEncCtxCreate">xmlSecEncCtxCreate</link> or
+		<link linkend="xmlSecEncCtxInitialize">xmlSecEncCtxInitialize</link>
+		functions.
+	    </para></listitem>
+	    <listitem><para>
+		Select start decryption &lt;enc:EncryptedData&gt; node.
+	    </para></listitem>
+	    <listitem><para>
+		Decrypt by calling <link linkend="xmlSecEncCtxDecrypt">xmlSecencCtxDecrypt</link> 
+		function.
+	    </para></listitem>
+	    <listitem><para>
+		Check returned value and if necessary consume encrypted data.
+	    </para></listitem>
+	    <listitem><para>
+		Destroy encryption context <link linkend="xmlSecEncCtx">xmlSecEncCtx</link>
+		using <link linkend="xmlSecEncCtxDestroy">xmlSecEncCtxDestroy</link> or
+		<link linkend="xmlSecEncCtxFinalize">xmlSecEncCtxFinalize</link>
+		functions.
+	    </para></listitem>
+	  </itemizedlist>
+	</para>
+	<para>
+	     <example>
+		<title>Decrypting a document.</title>
+		<programlisting><![CDATA[
+int 
+decrypt_file(const char* enc_file, const char* key_file) {
+    xmlDocPtr doc = NULL;
+    xmlNodePtr node = NULL;
+    xmlSecEncCtxPtr encCtx = NULL;
+    int res = -1;
+    
+    assert(enc_file);
+    assert(key_file);
+
+    /* load template */
+    doc = xmlParseFile(enc_file);
+    if ((doc == NULL) || (xmlDocGetRootElement(doc) == NULL)){
+	fprintf(stderr, "Error: unable to parse file \"%s\"\n", enc_file);
+	goto done;	
+    }
+    
+    /* find start node */
+    node = xmlSecFindNode(xmlDocGetRootElement(doc), xmlSecNodeEncryptedData, xmlSecEncNs);
+    if(node == NULL) {
+	fprintf(stderr, "Error: start node not found in \"%s\"\n", enc_file);
+	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 */
+    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;
+    }
+
+    /* decrypt the data */
+    if((xmlSecEncCtxDecrypt(encCtx, node) < 0) || (encCtx->result == NULL)) {
+        fprintf(stderr,"Error: decryption failed\n");
+	goto done;
+    }
+        
+    /* print decrypted data to stdout */
+    if(encCtx->resultReplaced != 0) {
+	fprintf(stdout, "Decrypted XML data:\n");
+	xmlDocDump(stdout, doc);
+    } else {
+	fprintf(stdout, "Decrypted binary data (%d bytes):\n", xmlSecBufferGetSize(encCtx->result));
+	if(xmlSecBufferGetData(encCtx->result) != NULL) {
+	    fwrite(xmlSecBufferGetData(encCtx->result), 
+	          1, 
+	          xmlSecBufferGetSize(encCtx->result),
+	          stdout);
+	}
+    }
+    fprintf(stdout, "\n");
+        
+    /* success */
+    res = 0;
+
+done:    
+    /* cleanup */
+    if(encCtx != NULL) {
+	xmlSecEncCtxDestroy(encCtx);
+    }
+    
+    if(doc != NULL) {
+	xmlFreeDoc(doc); 
+    }
+    return(res);
+}
+		]]></programlisting>
+	    <simpara><link linkend="xmlsec-example-decrypt1">Full Program Listing</link></simpara>
+	    </example>
+	</para>
+    </sect1>
+</chapter>