summaryrefslogtreecommitdiff
path: root/docs/api/src/chapters/sign-and-encrypt.sgml
diff options
context:
space:
mode:
Diffstat (limited to 'docs/api/src/chapters/sign-and-encrypt.sgml')
-rw-r--r--docs/api/src/chapters/sign-and-encrypt.sgml286
1 files changed, 286 insertions, 0 deletions
diff --git a/docs/api/src/chapters/sign-and-encrypt.sgml b/docs/api/src/chapters/sign-and-encrypt.sgml
new file mode 100644
index 00000000..72b969b6
--- /dev/null
+++ b/docs/api/src/chapters/sign-and-encrypt.sgml
@@ -0,0 +1,286 @@
+<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>
+