diff options
Diffstat (limited to 'docs/api/src/chapters/sign-and-encrypt.sgml')
-rw-r--r-- | docs/api/src/chapters/sign-and-encrypt.sgml | 286 |
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"><dsig:Signature/></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 + <enc:EncryptedData/> 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> + |