path: root/docs/api/chapters/sign-and-encrypt.sgml

<chapter id="xmlsec-notes-sign-encrypt">
    <title>Signing and encrypting documents.</title>
    <sect1 id="xmlsec-notes-sign-encrypt-overview">
        <title>Overview.</title>    
	<para>XML Security Library performs signature or encryption by processing 
	input xml or binary data and a template that specifies a signature or 
	encryption skeleton: the transforms, algorithms, the key selection 
	process. A template has the same structure as the desired result but 
	some of the nodes are empty. XML Security Library gets the key for 
	signature/encryption from keys managers using the information from 
	the template, does necessary computations and puts the results in 
	the template. Signature or encryption context controls the whole 
	process and stores the required temporary data.
	  <figure>
	    <title>The signature or encryption processing model.</title>
	    <graphic fileref="images/sign-enc-model.png" align="center"></graphic>
	  </figure>
	</para>
    </sect1>
    
    <sect1 id="xmlsec-notes-sign" >
	<title>Signing a document.</title>
	<para>The typical signature process includes following steps:
	  <itemizedlist>
	    <listitem><para>
		Prepare data for signature.
	    </para></listitem>
	    <listitem><para>
		Create or load signature template and select start
    		<ulink URL="http://www.w3.org/TR/xmldsig-core/#sec-Signature">&lt;dsig:Signature/&gt;</ulink>
		node.
	    </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>
		Load signature key in <link linkend="xmlSecKeysMngr">keys manager</link> 
		or generate a session key and set it in the signature context 
		(<structfield>signKey</structfield> member of 
		<link linkend="xmlSecDSigCtx">xmlSecDSigCtx</link> structure).
	    </para></listitem>
	    <listitem><para>
		Sign data by calling <link linkend="xmlSecDSigCtxSign">xmlSecDSigCtxSign</link> 
		function.
	    </para></listitem>
	    <listitem><para>
		Check returned value and consume signed data.
	    </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>Signing a template.</title>
		<programlisting><![CDATA[
/** 
 * sign_file:
 * @tmpl_file:		the signature template file name.
 * @key_file:		the PEM private key file name.
 *
 * Signs the #tmpl_file using private key from #key_file.
 *
 * Returns 0 on success or a negative value if an error occurs.
 */
int 
sign_file(const char* tmpl_file, const char* key_file) {
    xmlDocPtr doc = NULL;
    xmlNodePtr node = NULL;
    xmlSecDSigCtxPtr dsigCtx = NULL;
    int res = -1;
    
    assert(tmpl_file);
    assert(key_file);

    /* load template */
    doc = xmlParseFile(tmpl_file);
    if ((doc == NULL) || (xmlDocGetRootElement(doc) == NULL)){
	fprintf(stderr, "Error: unable to parse file \"%s\"\n", tmpl_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", tmpl_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 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, node) < 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-sign1">Full program listing</link></simpara>
		<simpara><link linkend="xmlsec-example-sign1-tmpl">Simple signature template file</link></simpara>
	    </example>
	</para>
    </sect1>
	
    <sect1 id="xmlsec-notes-encrypt">
	<title>Encrypting data.</title>
	<para>The typical encryption process includes following steps:
	  <itemizedlist>
	    <listitem><para>
		Prepare data for encryption.
	    </para></listitem>
	    <listitem><para>
		Create or load encryption template and select start
		&lt;enc:EncryptedData/&gt; node.
	    </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>
		Load encryption key in <link linkend="xmlSecKeysMngr">keys manager</link> 
		or generate a session key and set it in the encryption context
		(<structfield>encKey</structfield> member of 
		<link linkend="xmlSecEncCtx">xmlSecEncCtx</link> structure).
	    </para></listitem>
	    <listitem><para>
		Encrypt data by calling one of the following functions:
		<itemizedlist>
		    <listitem><para>
			<link linkend="xmlSecEncCtxBinaryEncrypt">xmlSecEncCtxBinaryEncrypt</link>
		    </para></listitem>
		    <listitem><para>
			<link linkend="xmlSecEncCtxXmlEncrypt">xmlSecEncCtxXmlEncrypt</link>
		    </para></listitem>
		    <listitem><para>
			<link linkend="xmlSecEncCtxUriEncrypt">xmlSecEncCtxUriEncrypt</link>
		    </para></listitem>
		</itemizedlist>
	    </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>Encrypting binary data with a template.</title>
		<programlisting><![CDATA[
/**
 * encrypt_file:
 * @tmpl_file:		the encryption template file name.
 * @key_file:		the Triple DES key file.
 * @data:		the binary data to encrypt.
 * @dataSize:		the binary data size.
 *
 * Encrypts binary #data using template from #tmpl_file and DES key from
 * #key_file.
 *
 * Returns 0 on success or a negative value if an error occurs.
 */
int 
encrypt_file(const char* tmpl_file, const char* key_file, const unsigned char* data, size_t dataSize) {
    xmlDocPtr doc = NULL;
    xmlNodePtr node = NULL;
    xmlSecEncCtxPtr encCtx = NULL;
    int res = -1;
    
    assert(tmpl_file);
    assert(key_file);
    assert(data);

    /* load template */
    doc = xmlParseFile(tmpl_file);
    if ((doc == NULL) || (xmlDocGetRootElement(doc) == NULL)){
	fprintf(stderr, "Error: unable to parse file \"%s\"\n", tmpl_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", tmpl_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;
    }

    /* encrypt the data */
    if(xmlSecEncCtxBinaryEncrypt(encCtx, node, data, dataSize) < 0) {
        fprintf(stderr,"Error: encryption failed\n");
    	goto done;
    }
        
    /* print encrypted data with document to stdout */
    xmlDocDump(stdout, doc);
    
    /* success */
    res = 0;

done:    
    /* cleanup */
    if(encCtx != NULL) {
	xmlSecEncCtxDestroy(encCtx);
    }
    
    if(doc != NULL) {
	xmlFreeDoc(doc); 
    }
    return(res);
}
		]]></programlisting>
		<simpara><link linkend="xmlsec-example-encrypt1">Full program listing</link></simpara>
		<simpara><link linkend="xmlsec-example-encrypt1-tmpl">Simple encryption template file</link></simpara>
	    </example>
	</para>
    </sect1>
</chapter>