docs/api/chapters/sign-and-encrypt.sgml

   1 <chapter id="xmlsec-notes-sign-encrypt">
   2     <title>Signing and encrypting documents.</title>
   3     <sect1 id="xmlsec-notes-sign-encrypt-overview">
   4         <title>Overview.</title>
   5         <para>XML Security Library performs signature or encryption by processing
   6         input xml or binary data and a template that specifies a signature or
   7         encryption skeleton: the transforms, algorithms, the key selection
   8         process. A template has the same structure as the desired result but
   9         some of the nodes are empty. XML Security Library gets the key for
  10         signature/encryption from keys managers using the information from
  11         the template, does necessary computations and puts the results in
  12         the template. Signature or encryption context controls the whole
  13         process and stores the required temporary data.
  14           <figure>
  15             <title>The signature or encryption processing model.</title>
  16             <graphic fileref="images/sign-enc-model.png" align="center"></graphic>
  17           </figure>
  18         </para>
  19     </sect1>
  20
  21     <sect1 id="xmlsec-notes-sign" >
  22         <title>Signing a document.</title>
  23         <para>The typical siganture process includes following steps:
  24           <itemizedlist>
  25             <listitem><para>
  26                 Prepare data for signature.
  27             </para></listitem>
  28             <listitem><para>
  29                 Create or load signature template and select start
  30                 <ulink URL="http://www.w3.org/TR/xmldsig-core/#sec-Signature">&lt;dsig:Signature/&gt;</ulink>
  31                 node.
  32             </para></listitem>
  33             <listitem><para>
  34                 Create signature context <link linkend="xmlSecDSigCtx">xmlSecDSigCtx</link>
  35                 using <link linkend="xmlSecDSigCtxCreate">xmlSecDSigCtxCreate</link> or
  36                 <link linkend="xmlSecDSigCtxInitialize">xmlSecDSigCtxInitialize</link>
  37                 functions.
  38             </para></listitem>
  39             <listitem><para>
  40                 Load signature key in <link linkend="xmlSecKeysMngr">keys manager</link>
  41                 or generate a session key and set it in the signature context
  42                 (<structfield>signKey</structfield> member of
  43                 <link linkend="xmlSecDSigCtx">xmlSecDSigCtx</link> structure).
  44             </para></listitem>
  45             <listitem><para>
  46                 Sign data by calling <link linkend="xmlSecDSigCtxSign">xmlSecDSigCtxSign</link>
  47                 function.
  48             </para></listitem>
  49             <listitem><para>
  50                 Check returned value and consume signed data.
  51             </para></listitem>
  52             <listitem><para>
  53                 Destroy signature context <link linkend="xmlSecDSigCtx">xmlSecDSigCtx</link>
  54                 using <link linkend="xmlSecDSigCtxDestroy">xmlSecDSigCtxDestroy</link> or
  55                 <link linkend="xmlSecDSigCtxFinalize">xmlSecDSigCtxFinalize</link>
  56                 functions.
  57             </para></listitem>
  58           </itemizedlist>
  59         </para>
  60         <para>
  61              <example>
  62                 <title>Signing a template.</title>
  63                 <programlisting><![CDATA[
  64 /**
  65  * sign_file:
  66  * @tmpl_file:          the signature template file name.
  67  * @key_file:           the PEM private key file name.
  68  *
  69  * Signs the #tmpl_file using private key from #key_file.
  70  *
  71  * Returns 0 on success or a negative value if an error occurs.
  72  */
  73 int
  74 sign_file(const char* tmpl_file, const char* key_file) {
  75     xmlDocPtr doc = NULL;
  76     xmlNodePtr node = NULL;
  77     xmlSecDSigCtxPtr dsigCtx = NULL;
  78     int res = -1;
  79
  80     assert(tmpl_file);
  81     assert(key_file);
  82
  83     /* load template */
  84     doc = xmlParseFile(tmpl_file);
  85     if ((doc == NULL) || (xmlDocGetRootElement(doc) == NULL)){
  86         fprintf(stderr, "Error: unable to parse file \"%s\"\n", tmpl_file);
  87         goto done;
  88     }
  89
  90     /* find start node */
  91     node = xmlSecFindNode(xmlDocGetRootElement(doc), xmlSecNodeSignature, xmlSecDSigNs);
  92     if(node == NULL) {
  93         fprintf(stderr, "Error: start node not found in \"%s\"\n", tmpl_file);
  94         goto done;
  95     }
  96
  97     /* create signature context, we don't need keys manager in this example */
  98     dsigCtx = xmlSecDSigCtxCreate(NULL);
  99     if(dsigCtx == NULL) {
 100         fprintf(stderr,"Error: failed to create signature context\n");
 101         goto done;
 102     }
 103
 104     /* load private key, assuming that there is not password */
 105     dsigCtx->signKey = xmlSecCryptoAppKeyLoad(key_file, xmlSecKeyDataFormatPem, NULL, NULL, NULL);
 106     if(dsigCtx->signKey == NULL) {
 107         fprintf(stderr,"Error: failed to load private pem key from \"%s\"\n", key_file);
 108         goto done;
 109     }
 110
 111     /* set key name to the file name, this is just an example! */
 112     if(xmlSecKeySetName(dsigCtx->signKey, key_file) < 0) {
 113         fprintf(stderr,"Error: failed to set key name for key from \"%s\"\n", key_file);
 114         goto done;
 115     }
 116
 117     /* sign the template */
 118     if(xmlSecDSigCtxSign(dsigCtx, node) < 0) {
 119         fprintf(stderr,"Error: signature failed\n");
 120         goto done;
 121     }
 122
 123     /* print signed document to stdout */
 124     xmlDocDump(stdout, doc);
 125
 126     /* success */
 127     res = 0;
 128
 129 done:
 130     /* cleanup */
 131     if(dsigCtx != NULL) {
 132         xmlSecDSigCtxDestroy(dsigCtx);
 133     }
 134
 135     if(doc != NULL) {
 136         xmlFreeDoc(doc);
 137     }
 138     return(res);
 139 }
 140                 ]]></programlisting>
 141                 <simpara><link linkend="xmlsec-example-sign1">Full program listing</link></simpara>
 142                 <simpara><link linkend="xmlsec-example-sign1-tmpl">Simple signature template file</link></simpara>
 143             </example>
 144         </para>
 145     </sect1>
 146
 147     <sect1 id="xmlsec-notes-encrypt">
 148         <title>Encrypting data.</title>
 149         <para>The typical encryption process includes following steps:
 150           <itemizedlist>
 151             <listitem><para>
 152                 Prepare data for encryption.
 153             </para></listitem>
 154             <listitem><para>
 155                 Create or load encryption template and select start
 156                 &lt;enc:EncryptedData/&gt; node.
 157             </para></listitem>
 158             <listitem><para>
 159                 Create encryption context <link linkend="xmlSecEncCtx">xmlSecEncCtx</link>
 160                 using <link linkend="xmlSecEncCtxCreate">xmlSecEncCtxCreate</link> or
 161                 <link linkend="xmlSecEncCtxInitialize">xmlSecEncCtxInitialize</link>
 162                 functions.
 163             </para></listitem>
 164             <listitem><para>
 165                 Load encryption key in <link linkend="xmlSecKeysMngr">keys manager</link>
 166                 or generate a session key and set it in the encryption context
 167                 (<structfield>encKey</structfield> member of
 168                 <link linkend="xmlSecEncCtx">xmlSecEncCtx</link> structure).
 169             </para></listitem>
 170             <listitem><para>
 171                 Encrypt data by calling one of the following functions:
 172                 <itemizedlist>
 173                     <listitem><para>
 174                         <link linkend="xmlSecEncCtxBinaryEncrypt">xmlSecEncCtxBinaryEncrypt</link>
 175                     </para></listitem>
 176                     <listitem><para>
 177                         <link linkend="xmlSecEncCtxXmlEncrypt">xmlSecEncCtxXmlEncrypt</link>
 178                     </para></listitem>
 179                     <listitem><para>
 180                         <link linkend="xmlSecEncCtxUriEncrypt">xmlSecEncCtxUriEncrypt</link>
 181                     </para></listitem>
 182                 </itemizedlist>
 183             </para></listitem>
 184             <listitem><para>
 185                 Check returned value and if necessary consume encrypted data.
 186             </para></listitem>
 187             <listitem><para>
 188                 Destroy encryption context <link linkend="xmlSecEncCtx">xmlSecEncCtx</link>
 189                 using <link linkend="xmlSecEncCtxDestroy">xmlSecEncCtxDestroy</link> or
 190                 <link linkend="xmlSecEncCtxFinalize">xmlSecEncCtxFinalize</link>
 191                 functions.
 192             </para></listitem>
 193           </itemizedlist>
 194         </para>
 195         <para>
 196              <example>
 197                 <title>Encrypting binary data with a template.</title>
 198                 <programlisting><![CDATA[
 199 /**
 200  * encrypt_file:
 201  * @tmpl_file:          the encryption template file name.
 202  * @key_file:           the Triple DES key file.
 203  * @data:               the binary data to encrypt.
 204  * @dataSize:           the binary data size.
 205  *
 206  * Encrypts binary #data using template from #tmpl_file and DES key from
 207  * #key_file.
 208  *
 209  * Returns 0 on success or a negative value if an error occurs.
 210  */
 211 int
 212 encrypt_file(const char* tmpl_file, const char* key_file, const unsigned char* data, size_t dataSize) {
 213     xmlDocPtr doc = NULL;
 214     xmlNodePtr node = NULL;
 215     xmlSecEncCtxPtr encCtx = NULL;
 216     int res = -1;
 217
 218     assert(tmpl_file);
 219     assert(key_file);
 220     assert(data);
 221
 222     /* load template */
 223     doc = xmlParseFile(tmpl_file);
 224     if ((doc == NULL) || (xmlDocGetRootElement(doc) == NULL)){
 225         fprintf(stderr, "Error: unable to parse file \"%s\"\n", tmpl_file);
 226         goto done;
 227     }
 228
 229     /* find start node */
 230     node = xmlSecFindNode(xmlDocGetRootElement(doc), xmlSecNodeEncryptedData, xmlSecEncNs);
 231     if(node == NULL) {
 232         fprintf(stderr, "Error: start node not found in \"%s\"\n", tmpl_file);
 233         goto done;
 234     }
 235
 236     /* create encryption context, we don't need keys manager in this example */
 237     encCtx = xmlSecEncCtxCreate(NULL);
 238     if(encCtx == NULL) {
 239         fprintf(stderr,"Error: failed to create encryption context\n");
 240         goto done;
 241     }
 242
 243     /* load DES key */
 244     encCtx->encKey = xmlSecKeyReadBinaryFile(xmlSecKeyDataDesId, key_file);
 245     if(encCtx->encKey == NULL) {
 246         fprintf(stderr,"Error: failed to load des key from binary file \"%s\"\n", key_file);
 247         goto done;
 248     }
 249
 250     /* set key name to the file name, this is just an example! */
 251     if(xmlSecKeySetName(encCtx->encKey, key_file) < 0) {
 252         fprintf(stderr,"Error: failed to set key name for key from \"%s\"\n", key_file);
 253         goto done;
 254     }
 255
 256     /* encrypt the data */
 257     if(xmlSecEncCtxBinaryEncrypt(encCtx, node, data, dataSize) < 0) {
 258         fprintf(stderr,"Error: encryption failed\n");
 259         goto done;
 260     }
 261
 262     /* print encrypted data with document to stdout */
 263     xmlDocDump(stdout, doc);
 264
 265     /* success */
 266     res = 0;
 267
 268 done:
 269     /* cleanup */
 270     if(encCtx != NULL) {
 271         xmlSecEncCtxDestroy(encCtx);
 272     }
 273
 274     if(doc != NULL) {
 275         xmlFreeDoc(doc);
 276     }
 277     return(res);
 278 }
 279                 ]]></programlisting>
 280                 <simpara><link linkend="xmlsec-example-encrypt1">Full program listing</link></simpara>
 281                 <simpara><link linkend="xmlsec-example-encrypt1-tmpl">Simple encryption template file</link></simpara>
 282             </example>
 283         </para>
 284     </sect1>
 285 </chapter>
 286