You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@santuario.apache.org by co...@apache.org on 2018/06/28 10:52:08 UTC
svn commit: r1031841 [1/2] - in /websites/production/santuario/content:
cache/main.pageCache ccredits.html cfaq.html cinstallation.html
cprogramming.html creleasenotes.html download.html index.html
Author: coheigea
Date: Thu Jun 28 10:52:08 2018
New Revision: 1031841
Log:
Updating website manually
Modified:
websites/production/santuario/content/cache/main.pageCache
websites/production/santuario/content/ccredits.html
websites/production/santuario/content/cfaq.html
websites/production/santuario/content/cinstallation.html
websites/production/santuario/content/cprogramming.html
websites/production/santuario/content/creleasenotes.html
websites/production/santuario/content/download.html
websites/production/santuario/content/index.html
Modified: websites/production/santuario/content/cache/main.pageCache
==============================================================================
Binary files - no diff available.
Modified: websites/production/santuario/content/ccredits.html
==============================================================================
--- websites/production/santuario/content/ccredits.html (original)
+++ websites/production/santuario/content/ccredits.html Thu Jun 28 10:52:08 2018
@@ -99,17 +99,7 @@ Apache Santuario -- c_credits
<td height="100%">
<!-- Content -->
<div class="wiki-content">
-<div id="ConfluenceContent"><h1 id="c_credits-Credits">Credits</h1>
-
-<h1 id="c_credits-SoftwareUsed">Software Used</h1>
-
-<p>The Apache XML Security for C++ package makes heavy use of the <a shape="rect" class="external-link" href="http://xml.apache.org/xalan-c/">Xalan-C</a> and <a shape="rect" class="external-link" href="http://xerces.apache.org/xerces-c/">Xerces-C++</a> libraries from the Apache Software Foundation.</p>
-
-<p>This product includes cryptographic software written by Eric Young (eay@cryptsoft.com). This product includes software written by Tim Hudson (tjh@cryptsoft.com).</p>
-
-<p>This product includes software developed by the OpenSSL Project for use in the <a shape="rect" class="external-link" href="http://www.openssl.org/" rel="nofollow">OpenSSL Toolkit</a>.</p>
-
-<p>The license documents for Xerces, Xalan and OpenSSL are contained in the <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/santuario/xml-security-cpp/trunk/doc/">doc</a> directory in SVN and in the doc directory in distributions of the C++ source code.</p></div>
+<div id="ConfluenceContent"><h1 id="c_credits-Notes">Notes</h1><p>The software is currently maintained solely at the largesse of the <a shape="rect" class="external-link" href="https://www.shibboleth.net" rel="nofollow">Shibboleth Consortium</a>, which has subsidized all development time on this project for many years. It would likely be unsupported at present if not for that project.</p><h1 id="c_credits-SoftwareUsed">Software Used</h1><p>The Apache XML Security for C++ package makes heavy use of the <a shape="rect" class="external-link" href="http://xml.apache.org/xalan-c/">Xalan-C</a> and <a shape="rect" class="external-link" href="http://xerces.apache.org/xerces-c/">Xerces-C++</a> libraries from the Apache Software Foundation.</p><p>This product includes cryptographic software written by Eric Young (eay@cryptsoft.com). This product includes software written by Tim Hudson (tjh@cryptsoft.com).</p><p>This product includes software developed by the OpenSSL Project for use in the <a
shape="rect" class="external-link" href="http://www.openssl.org/" rel="nofollow">OpenSSL Toolkit</a>.</p><p>The license documents for Xerces, Xalan and OpenSSL are contained in the <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/santuario/xml-security-cpp/trunk/doc/">doc</a> directory in SVN and in the doc directory in distributions of the C++ source code.</p></div>
</div>
<!-- Content -->
</td>
Modified: websites/production/santuario/content/cfaq.html
==============================================================================
--- websites/production/santuario/content/cfaq.html (original)
+++ websites/production/santuario/content/cfaq.html Thu Jun 28 10:52:08 2018
@@ -99,65 +99,7 @@ Apache Santuario -- c_faq
<td height="100%">
<!-- Content -->
<div class="wiki-content">
-<div id="ConfluenceContent"><h1 id="c_faq-FrequentlyAskedQuestions-ApacheXMLSecurityforC++">Frequently Asked Questions - Apache XML Security for C++</h1>
-
-<h3 id="c_faq-1.CompilingandUsingtheLibrary">1. Compiling and Using the Library</h3>
-
-<h5 id="c_faq-1.1.IsOpenSSLrequired?">1.1. Is OpenSSL required?</h5>
-
-<p>The main development work for the library is done using OpenSSL, so this is the recommended option. However, Windows Crypto API and NSS interfaces are also now provided.</p>
-
-<p>It is also possible to implement interfaces for other cryptographic libraries and pass them into the xml-security-c library during initialisation (via the XSECPlatformUtils::Initialise() call).</p>
-
-<h5 id="c_faq-1.2.DoesthelibraryprovideafullC++wrapperforOpenSSL?">1.2. Does the library provide a full C++ wrapper for OpenSSL?</h5>
-
-<p>The C++ crypto interface layer provided for the library provides only the smallest subset of cryptographic functions necessary for the library to make calls to the provided library. Applications will need to work directly with OpenSSL (or other libraries) to read and manipulate encryption keys that should then be wrapped in XSECCrypto* objects and passed into the library.</p>
-
-<h5 id="c_faq-1.3.WhatisWinCAPI?">1.3. What is WinCAPI?</h5>
-
-<p>WinCAPI is the developmental interface being built to give users of the library access to the Windows Cryptographic library.</p>
-
-<p>It is not a C API wrapper for the overall library.</p>
-
-<h5 id="c_faq-1.4.IsXalanrequired?">1.4. Is Xalan required?</h5>
-
-<p>The library can be compiled without linking to Xalan-c. However doing so will disable support for XPath and XSLT transformations.</p>
-
-<p>To disable Xalan-c support either use --without-xalan when running configure on UNIX, or use the VC++ "without Xalan" settings.</p>
-
-<h5 id="c_faq-1.5.AreversionsofXalanpriorto1.6supported?">1.5. Are versions of Xalan prior to 1.6 supported?</h5>
-
-<p>No. Whilst the functionality required is available in prior versions, the location of include files changed in 1.6. A decision was made in version 1.0.0 of Apache XML Security for C++ to update the source to support these new locations.</p>
-
-<h5 id="c_faq-1.6.IsignadocumentandwhenItrytoverifyusingthesamekey,itfails">1.6. I sign a document and when I try to verify using the same key, it fails</h5>
-
-<p>After you have created the XMLSignature object, before you sign the document, you must embed the signature element in the owning document (which is returned by the call to DSIGSignature::createBlankSignature(...)) before calling the DSIGSignature::sign() method,</p>
-
-<p>During canonicalisation of the SignedInfo element, the library looks at the parent and ancestor nodes of the Signature element to find any namespaces that the SignedInfo node has inherited. Any that are found are embedded in the canonical form of the SignedInfo. (This is not true when Exclusive Canonicalisation is used, but it is still good practice to insert the element node prior to the sign() method being called).</p>
-
-<p>If you have not embedded the signature node in the document, it will not have any parent or ancestor nodes, so it will not inherit their namespaces. If you then embed it in the document and call verify(), the namespaces will be found and the canonical form of SignedInfo will be different to that generated during sign().</p>
-
-<h5 id="c_faq-1.7.HowdoesthelibraryidentifyIdattributes?">1.7. How does the library identify Id attributes?</h5>
-
-<p>During a signing operation, finding the correct Id attribute is vital. Should the wrong Id Attribute be used, the wrong part of the document will be identified, and what the user signs will not be what they expect to sign.</p>
-
-<p>The preferred method (and the method the library uses first) of finding an Id is via the DOM Level 2 call DOMDocument::getElementById(). This indicates to the library that the Id has been explicitly identified via a schema, DTD or during document building. However, if this call fails, the library will then search the document for attributes named "Id" or "id" with the appropriate value. The first one found will be used as document fragment identifier.</p>
-
-<p>As of version 1.2, the library also provides methods to allow callers to set additional Id attribute names. This can be done in one of two ways. DSIGSignature::registerIdAttributeName() will register a new name that will not be matched to a namespace. DSIGDSignature::registerIdAttribiteNameNS() will register an attribute name together with the namespace in which the attribute resides.</p>
-
-<p>As this is a potential security exposure, this behaviour can be disabled using a call to DISGSignatures::setIdByAttributeName(false). There are also methods provided to modify the list of attributes that will be searched. However it is recommended that these methods not be used, and DOM attributes of Type=ID be used.</p>
-
-<p><strong>Warning</strong> In version 1.1 and above, the library defaults to searching for Id attributes by name if a search by Id fails. As this is a potential security risk, this behaviour may be changed in a future version of the library.</p>
-
-<h5 id="c_faq-1.8.WhatpartsoftheXKMSspecificationdoesthelibrarysupport?">1.8. What parts of the XKMS specification does the library support?</h5>
-
-<p>The library currently supports X-KISS (XML Key Information Service Specification) message generation and processing. Support for X-KRSS (XML Key Registration Service Specification) will be provided in version 1.3 of the library.</p>
-
-<h5 id="c_faq-1.9.DoesthelibraryprovideaprogrammaticXKMSclient?">1.9. Does the library provide a programmatic XKMS client?</h5>
-
-<p>Not yet. A command line tool xklient is provided for generating and processing messages. This can be used as an example for processing XKMS messages.</p>
-
-<p>A programmatic client will be provided in version 1.3 of the Apache XML Security for C++library.</p></div>
+<div id="ConfluenceContent"><h1 id="c_faq-FrequentlyAskedQuestions-ApacheXMLSecurityforC++">Frequently Asked Questions - Apache XML Security for C++</h1><h3 id="c_faq-CompilingandRequirements">Compiling and Requirements</h3><h5 id="c_faq-WhatarethesignificantchangeswithV2.0.0?">What are the significant changes with V2.0.0?</h5><p>The API has been slightly updated and a variety of deprecated methods have been removed, along with many public references to an older set of enumeration constants for algorithms of various sorts. The public APIs are now primarily URI-based such that future algorithm additions should not require public changes. So most code will be slightly broken but should require minimal modification to be updated.</p><p>There are significant changes to the support status of parts of the library that lack maintainers. The following features are deprecated at present and at risk of future removal:</p><ul><li>NSS support</li><li>WinCAPI support</li><li>XKMS features</li></
ul><p>All those features can be left out of the build to ensure no usage of them by downstream projects wishing to limit their security exposure and this is advisable.</p><p>Finally, the set of platforms formally supported by the maintainer of the library is limited, and no longer includes Solaris. Most releases of the library will likely build on most platforms, including Solaris, but likely with patches required that will be happily accepted by the project. The formal set of platforms supported is exactly the set <a shape="rect" class="external-link" href="https://wiki.shibboleth.net/confluence/display/SP3/SystemRequirements" rel="nofollow">supported</a> by the Shibboleth Project, whose resources are the sum total actively maintaining this code.</p><h5 id="c_faq-IsOpenSSLrequired?">Is OpenSSL required?</h5><p>While Windows Crypto API and NSS interfaces are also provided, they are moribund, lack modern algorithm support, and are deprecated at present.</p><p>It is possible to implem
ent interfaces for other cryptographic libraries and pass them into the xml-security-c library during initialisation (via the XSECPlatformUtils::Initialise() call).</p><p>TL;DR, yes, OpenSSL is required.</p><h5 id="c_faq-DoesthelibraryprovideafullC++wrapperforOpenSSL?">Does the library provide a full C++ wrapper for OpenSSL?</h5><p>No. The C++ crypto interface layer provided for the library provides only the subset of cryptographic functions necessary for the library to make calls to the provided library. Applications will need to work directly with OpenSSL (or other libraries) to read and manipulate encryption keys that should then be wrapped in XSECCrypto* objects and passed into the library. There have been additions to the API over time to make the primitives in this library more usable as mechanisms for general operations, but they are not complete.</p><h5 id="c_faq-IsXercesrequired?">Is Xerces required?</h5><p>Yes, and the library now requires V3.2.0 or above. No older version
s of Xerces are supported so any such use is highly ill-advised in any event.</p><h5 id="c_faq-IsXalanrequired?">Is Xalan required?</h5><p>The library can be compiled without linking to Xalan. However doing so will disable support for XPath and XSLT transformations. If used, only the very latest Xalan release, 1.0.11, will successfully build with Xerces 3.2 and this library.</p><h3 id="c_faq-LibraryUse">Library Use</h3><h5 id="c_faq-IsignadocumentandwhenItrytoverifyusingthesamekey,itfails">I sign a document and when I try to verify using the same key, it fails</h5><p>After you have created the XMLSignature object, before you sign the document, you must embed the signature element in the owning document (which is returned by the call to DSIGSignature::createBlankSignature(...)) before calling the DSIGSignature::sign() method,</p><p>During canonicalisation of the SignedInfo element, the library looks at the parent and ancestor nodes of the Signature element to find any namespaces that
the SignedInfo node has inherited. Any that are found are embedded in the canonical form of the SignedInfo. (This is not true when Exclusive Canonicalisation is used, but it is still good practice to insert the element node prior to the sign() method being called).</p><p>If you have not embedded the signature node in the document, it will not have any parent or ancestor nodes, so it will not inherit their namespaces. If you then embed it in the document and call verify(), the namespaces will be found and the canonical form of SignedInfo will be different to that generated during sign().</p><h5 id="c_faq-HowdoesthelibraryidentifyIdattributes?">How does the library identify Id attributes?</h5><p>During a signing operation, finding the correct Id attribute is vital. Should the wrong Id Attribute be used, the wrong part of the document will be identified, and what the user signs will not be what they expect to sign.</p><p>The preferred method (and the method the library uses first) of
finding an Id is via the DOM Level 2 call DOMDocument::getElementById(). This indicates to the library that the Id has been explicitly identified via a schema, DTD or during document building. However, if this call fails, the library will then search the document for attributes named "Id" or "id" with the appropriate value. The first one found will be used as document fragment identifier.</p><p>As of version 1.2, the library also provides methods to allow callers to set additional Id attribute names. This can be done in one of two ways. DSIGSignature::registerIdAttributeName() will register a new name that will not be matched to a namespace. DSIGDSignature::registerIdAttribiteNameNS() will register an attribute name together with the namespace in which the attribute resides.</p><p>As this is a potential security exposure, this behaviour can be disabled using a call to DISGSignatures::setIdByAttributeName(false). There are also methods provided to modify the list of attributes that w
ill be searched. However it is recommended that these methods not be used, and DOM attributes of Type=ID be used.</p><p><strong>Warning</strong> In version 1.1 and above, the library defaults to searching for Id attributes by name if a search by Id fails. As this is a potential security risk, this behaviour may be changed in a future version of the library.</p><h5 id="c_faq-WhatpartsoftheXKMSspecificationdoesthelibrarysupport?">What parts of the XKMS specification does the library support?</h5><p>The library currently supports X-KISS (XML Key Information Service Specification) message generation and processing. XKMS support is optional with V2.0.0 and can be omitted from the build.</p><p>The XKMS support is deprecated.</p><h5 id="c_faq-DoesthelibraryprovideaprogrammaticXKMSclient?">Does the library provide a programmatic XKMS client?</h5><p>A command line tool xklient is provided for generating and processing messages. This can be used as an example for processing XKMS messages.</p>
<p><br clear="none"></p></div>
</div>
<!-- Content -->
</td>
Modified: websites/production/santuario/content/cinstallation.html
==============================================================================
--- websites/production/santuario/content/cinstallation.html (original)
+++ websites/production/santuario/content/cinstallation.html Thu Jun 28 10:52:08 2018
@@ -99,112 +99,7 @@ Apache Santuario -- c_installation
<td height="100%">
<!-- Content -->
<div class="wiki-content">
-<div id="ConfluenceContent"><h1 id="c_installation-InstallingtheApacheXMLSecurityforC++Library">Installing the Apache XML Security for C++ Library</h1>
-
-<h3 id="c_installation-Prerequisites">Prerequisites</h3>
-
-<p>The library requires one of OpenSSL, NSS, or WinCAPI for cryptographic support, but only OpenSSL is well-tested. Xalan-C is also required if XPath and/or XSLT transformations are required.</p>
-
-<p>Version 1.6.0 of the library has been tested with versions 3.x and 2.8.0 of Xerces-C, and Version 0.9.7 (and above) of OpenSSL. Xalan-C has no official releases that will build successfully with Xerces-C 3.x.</p>
-
-<h3 id="c_installation-Gettingthesource">Getting the source</h3>
-
-<p>You can download the sources via WWW in the distribution directory from one of the Apache mirrors.</p>
-
-<p>This project's SVN repository can be checked out directly from <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/santuario/xml-security-cpp/trunk/">here</a></p>
-
-<p>A HTTP interface to browse the sources online is available <a shape="rect" class="external-link" href="http://svn.apache.org/viewvc/santuario/xml-security-cpp/trunk/">here</a></p>
-
-<h3 id="c_installation-BuildingforUNIX">Building for UNIX</h3>
-
-<p>XML Security C++ is currently fully supported on Red Hat and SUSE Linux, Solaris, and Mac OS X. It has been built and tested using GNU gcc 3.x/4.x and Sun Workshop (Solaris).</p>
-
-<h5 id="c_installation-SetuptheEnvironment">Set up the Environment</h5>
-
-<p>The build process has been corrected as much as possible to rely on standard configure and make commands and not environment variables.</p>
-
-<p>If configure cannot find anything for Xalan, it will assume that you are not interested in XPath or XSLT support and will compile without linking to Xalan. Any attempt to use these features will raise an exception in the library.</p>
-
-<h5 id="c_installation-Configure">Configure</h5>
-
-<p>Now go to the root directory and run the command ./configure. This will create the necessary makefiles and header files necessary to build the package.</p>
-
-<p>In addition to the standard options, configure can be passed a number of XSEC specific options :</p>
-
-<ul><li>--without-xalan disable linkage to Xalan.</li><li>--with-xerces=<dir> define Xerces directory</li><li>--with-openssl=<dir> define OpenSSL directory</li><li>--with-nss=<dir> define NSS directory (must be used to get NSS support)</li><li>--enable-debug cause the library to be built with symbols</li></ul>
-
-
-<p>Using the --without-xalan option will automatically mean that the library does not support XPath or XSLT transformations (although envelope transforms will work as the library can perform these without going through an XPath transform).</p>
-
-<h5 id="c_installation-Compile">Compile</h5>
-
-<p>Assuming the output of the above command looks reasonable simply type make (or gmake) in the base directory. This will build the library. In addition, make tools will make the tools (or examples) in the src/tools directory.</p>
-
-<p>The make process will create three directories in the distribution directory:</p>
-
-<p> 1. include - All public header files are copied here<br clear="none">
- 2. bin - Where the tools are placed once compiles<br clear="none">
- 3. lib - Where the shared library is place</p>
-
-<p>You may need to set up your LD_LIBRARY_PATH environment variable to ensure ld.so will find the new shared libraries.</p>
-
-<p>Finally - you can use make clean and make distclean to remove all binaries and libraries (former) and build scripts (latter)</p>
-
-<h5 id="c_installation-Install">Install</h5>
-
-<p>make install can be used to install the library and the include files into the relevant directories (which can be set via the configure script using the various --prefix= options.</p>
-
-<h3 id="c_installation-BuildingforWindows">Building for Windows</h3>
-
-<p>Apache XML Security for C++ has been built and tested on Microsoft's Visual C++ 6.0 and 2005/2008/2010 compilers. The following subsections briefly describe how to rebuild the library, tools and samples using the supplied workspaces. The specific information is for VC6, but the process for later versions is similar.</p>
-
-<p>The library can be built without OpenSSL on a Windows platform. (The WinCAPI provider will be used instead). See below for details on how to do this. This is experimental, but should work for some scenarios.</p>
-
-<h5 id="c_installation-SetupDirectories">Setup Directories</h5>
-
-<p>The workspace and project files provided do not make any assumptions about where Xerces, Xalan or OpenSSL might be on the system. The first step is therefore to configure VC directories under Tools->Options (Directories).</p>
-
-<p>For the Include directories you will need something similar to my setup below (replacing D:\PROG\CLIB\.. with the appropriate path on your system).</p>
-
-<p><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image" src="cinstallation.data/vc6a.gif"></span></p>
-
-<p>Similarly the library directories will need to be added to. Note that in the example below, I use both Debug and Release libraries for Xalan and Xerces. As provided, the workspace projects link to the debug libraries for XSEC Debug and Release for XSEC Release.</p>
-
-<p><span class="confluence-embedded-file-wrapper"><img class="confluence-embedded-image" src="cinstallation.data/vc6b.gif"></span></p>
-
-<h5 id="c_installation-Configure.1">Configure</h5>
-
-<p>If you are using Xalan and OpenSSL, no configuration is required when building from the Visual C++ v6.0 workspace.</p>
-
-<p>If you wish to disable OpenSSL, you should edit the file .../src/framework/XSECW32Config.hpp and comment out the line #define HAVE_OPENSSL 1. This will effectively remove support for OpenSSL from the library as it is being compiled.</p>
-
-<p>You will also need to remove the library module libeay32.lib from the link->General settings in each of the projects in the XSEC workspace.</p>
-
-<p>To enable support for the Windows Crypto API, edit the XSECW32Config.hpp file and uncomment the line #define HAVE_WINCAPI 1</p>
-
-<p>To disable support for Xalan, a similar process is followed. Edit the XSECW32Config.hpp file, and uncomment the XSEC_NO_XALAN line. This will remove all support for Xalan from the various source code files.</p>
-
-<p>When compiling, using the "...No Xalan configurations for each project. These are the same as the normal debug or release builds, but the Xalan library is not linked in.</p>
-
-<h1 id="c_installation-BuildLibraryandTools">Build Library and Tools</h1>
-
-<p>The main workspace (for VC 6.0) is found in :</p>
-
-<p>.../Projects/VC6.0/xsec/xsec.dsw</p>
-
-<p>You can load this to build the tools or the library using the relevant project. (The library is xsec_lib.) Project files for VC++ 7.0 and 8.0 also exist in the appropriate Project directories.</p>
-
-<p>Note that as of version 1.3.1, Xerces 3.0 is supported. However this uses an updated library file name, so this must be modified in all the projects in the workspace. This can be set in the Linker option for all versions of Visual C++.</p>
-
-<p>Samples can be built using the workspace found in :</p>
-
-<p>.../src/Projects/VC6.0/Samples/Samples.dsw</p>
-
-<p>All output will be sent to</p>
-
-<p>.../Build/Win32/VC6/Debug</p>
-
-<p>for the debug builds and Release for the release.</p></div>
+<div id="ConfluenceContent"><h1 id="c_installation-InstallingtheApacheXMLSecurityforC++Library">Installing the Apache XML Security for C++ Library</h1><h3 id="c_installation-Prerequisites">Prerequisites</h3><p>The library requires one of OpenSSL, NSS, or WinCAPI for cryptographic support, but only OpenSSL is well-tested. Xalan-C is also required if XPath and/or XSLT transformations are required.</p><p>Version 2.0.0 of the library requires Xerces-C 3.2+ and (if used) Xalan-C 1.0.11+. It supports OpenSSL 1.1.0 but maintains support for older releases for now.</p><h3 id="c_installation-Gettingthesource">Getting the source</h3><p>You can download the sources via WWW in the distribution directory from one of the Apache mirrors.</p><p>This project's SVN repository can be checked out directly from <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/santuario/xml-security-cpp/trunk/">here</a></p><p>A HTTP interface to browse the sources online is available <a shape="
rect" class="external-link" href="http://svn.apache.org/viewvc/santuario/xml-security-cpp/trunk/">here</a></p><h3 id="c_installation-BuildingforUNIX">Building for UNIX</h3><p>XML Security C++ is currently fully supported on a few Linux distributions, principally Red Hat and derivatives, and macOS. It has been built and tested using a variety of compilers, but mostly gcc/g++.</p><h5 id="c_installation-SetuptheEnvironment">Set up the Environment</h5><p>The build process has been corrected as much as possible to rely on standard configure and make commands and not environment variables. It is a pkg-config-based build as of V2.0.0, and will auto-detect the right settings to use when possible.</p><p>If configure cannot find anything for Xalan, it will assume that you are not interested in XPath or XSLT support and will compile without linking to Xalan. Any attempt to use these features will raise an exception in the library.</p><p>You should normally provide one of --with-openssl or --wi
th-nss to the build to ensure that at least one of the desired provider plugins is built and available. Saying nothing may result in the build completing but with no actual plugin included.</p><h5 id="c_installation-Configure">Configure</h5><p>Now go to the root directory and run the command ./configure. This will create the necessary makefiles and header files necessary to build the package.</p><p>In addition to the standard options, configure can be passed a number of XSEC specific options :</p><ul><li>--without-xalan disable linkage to Xalan.</li><li>--with-openssl to require OpenSSL support be available</li><li>--with-nss to require NSS support be available</li><li>--enable-xkms to include the XKMS support</li></ul><p>Using the --without-xalan option will automatically mean that the library does not support XPath or XSLT transformations (although envelope transforms will work as the library can perform these without going through an XPath transform).</p><h5 id="c_installation-Co
mpile">Compile</h5><p>Assuming the output of the above command looks reasonable simply type make (or gmake) in the base directory. This will build the library. In addition, make tools will make the tools (or examples) in the src/tools directory.</p><p>The make process will create three directories in the distribution directory:</p><p>1. include - All public header files are copied here<br clear="none"> 2. bin - Where the tools are placed once compiles<br clear="none"> 3. lib - Where the shared library is place</p><p>You may need to set up your LD_LIBRARY_PATH environment variable to ensure ld.so will find the new shared libraries.</p><p>Finally - you can use make clean and make distclean to remove all binaries and libraries (former) and build scripts (latter)</p><h5 id="c_installation-Install">Install</h5><p>make install can be used to install the library and the include files into the relevant directories (which can be set via the configure script using the various --prefix= option
s.</p><h3 id="c_installation-BuildingforWindows">Building for Windows</h3><p>Apache XML Security for C++ has been built and tested on Microsoft's VS 2017 compiler series but you will need to do substantial manual work to the solution files for your particular environment and to locate dependencies.</p><p>The library can be built without OpenSSL on a Windows platform by using WinCAPI, but this is deprecated.</p><p>Some of the settings you may need to touch will be in the .../src/framework/XSECW32Config.hpp file, including macros to determine whether Xalan, OpenSSL, NSS, WinCAPI, and/or XKMS support are included in the build.</p><p>The solution files include a "Minimal" debug and release option that presumes no Xalan, NSS, WinCAPI, or XKMS support.</p><p>Apologies for the incompleteness of this information but the project is now maintained solely for use by a single downstream project and it has build workflows that do not require a fully-working solution file for arbitrary project co
nsumers at this time.</p><p><br clear="none"></p></div>
</div>
<!-- Content -->
</td>
Modified: websites/production/santuario/content/cprogramming.html
==============================================================================
--- websites/production/santuario/content/cprogramming.html (original)
+++ websites/production/santuario/content/cprogramming.html Thu Jun 28 10:52:08 2018
@@ -109,33 +109,8 @@ Apache Santuario -- c_programming
<td height="100%">
<!-- Content -->
<div class="wiki-content">
-<div id="ConfluenceContent"><h1 id="c_programming-XMLSignatureProgramming">XML Signature Programming</h1>
-
-<h3 id="c_programming-Overview">Overview</h3>
-
-<p>There are two main signature modes of operation for the libraries. Signing and verifying. Verifying is the simplest operation, as it (generally) operates on a DOM <Signature> structure that has already been created.</p>
-
-<p>Signing on the other hand can be more difficult, as there may be a requirement to create the DOM structure necessary for the signature prior to the actual signing operation.</p>
-
-<p>The rest of this section provides a very high level overview on how to use the library for signing and verification of signatures.</p>
-
-<p>Two samples are provided :</p>
-
-<ul><li>Simple HMAC Signing</li><li>Simple DSA Validation</li></ul>
-
-
-<p>The code snippets are taken directly from some of the sample code provided in the src/samples directory in the distribution. More information on the API can be found in the API Documentation.</p>
-
-<h3 id="c_programming-AsimpleHMACSigningexample">A simple HMAC Signing example</h3>
-
-<p>The first example is based on the simpleHMAC.cpp code in samples. It creates an XML letter, the appends a dummy signature to the end, using an enveloped-signature transform.</p>
-
-<h5 id="c_programming-Setup">Setup</h5>
-
-<p>The following code snippet initialises Xerces, Xalan and XSEC. Note that the enveloped transform is implemented using an XPath expression, so it is imperitive the Xalan libraries are initialised.</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">
+<div id="ConfluenceContent"><div class="confluence-information-macro confluence-information-macro-note"><span class="aui-icon aui-icon-small aui-iconfont-warning confluence-information-macro-icon"></span><div class="confluence-information-macro-body"><p>Much of this information may be slightly inaccurate as it has not been updated for V2.0.0 of the library.</p></div></div><h1 id="c_programming-XMLSignatureProgramming">XML Signature Programming</h1><h3 id="c_programming-Overview">Overview</h3><p>There are two main signature modes of operation for the libraries. Signing and verifying. Verifying is the simplest operation, as it (generally) operates on a DOM <Signature> structure that has already been created.</p><p>Signing on the other hand can be more difficult, as there may be a requirement to create the DOM structure necessary for the signature prior to the actual signing operation.</p><p>The rest of this section provides a very high level overview on how to use the library fo
r signing and verification of signatures.</p><p>Two samples are provided :</p><ul><li>Simple HMAC Signing</li><li>Simple DSA Validation</li></ul><p>The code snippets are taken directly from some of the sample code provided in the src/samples directory in the distribution. More information on the API can be found in the API Documentation.</p><h3 id="c_programming-AsimpleHMACSigningexample">A simple HMAC Signing example</h3><p>The first example is based on the simpleHMAC.cpp code in samples. It creates an XML letter, the appends a dummy signature to the end, using an enveloped-signature transform.</p><h5 id="c_programming-Setup">Setup</h5><p>The following code snippet initialises Xerces, Xalan and XSEC. Note that the enveloped transform is implemented using an XPath expression, so it is imperitive the Xalan libraries are initialised.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default">
int main (int argc, char **argv) {
try {
@@ -162,14 +137,8 @@ int main (int argc, char **argv) {
DOMDocument *doc = createLetter(impl);
DOMElement *rootElem = doc->getDocumentElement();
</pre>
-</div></div>
-
-<p>In the sample application, the call to createLetter(impl) simply creates a letter DOM structure with a to and from address and some text. This is done using standard DOM calls via Xerces.</p>
-
-<p>Once the system is initialised and the DOM document is created, a DSIGSignature object is created via the XSECProvider interface class. The signature object is then used to create a blank signature DOM node structure which is then inserted at the end of the document.</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">
+</div></div><p>In the sample application, the call to createLetter(impl) simply creates a letter DOM structure with a to and from address and some text. This is done using standard DOM calls via Xerces.</p><p>Once the system is initialised and the DOM document is created, a DSIGSignature object is created via the XSECProvider interface class. The signature object is then used to create a blank signature DOM node structure which is then inserted at the end of the document.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default">
XSECProvider prov;
DSIGSignature *sig;
DOMElement *sigNode;
@@ -188,19 +157,8 @@ int main (int argc, char **argv) {
SIGNATURE_HMAC,
HASH_SHA1);
</pre>
-</div></div>
-
-<p>The call to newSignature creates a signature object only. No DOM nodes are created at this point. The call to setDSIGNSPrefix tells the XSEC library what namespace prefix to use for the signature object when it starts to create DOM nodes (in this case "ds" will be used). By default, the library will use "dsig" as the prefix for the name space for Digital Signatures.</p>
-
-<p>Finally, the call to sig->createBlankSignature sets up both the DOM structure and the XSEC objects for a new signature with no <Reference> elements. In this case, the signature will be made using Commented C14n canonicalisation, and a HMAC-SHA1 signature.</p>
-
-<p><strong>Warning:</strong> The XSECProvider class still "owns" the DSIGSignature object. To delete the object, the original provider.release(sig) call should be used. Never delete a DSIGSignature object directly.</p>
-
-<h5 id="c_programming-CreateaReferenceandSign">Create a Reference and Sign</h5>
-
-<p>Now that the signature object is created, the signature is inserted into the document, and a reference is created and set for an enveloping transform.</p>
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">
+</div></div><p>The call to newSignature creates a signature object only. No DOM nodes are created at this point. The call to setDSIGNSPrefix tells the XSEC library what namespace prefix to use for the signature object when it starts to create DOM nodes (in this case "ds" will be used). By default, the library will use "dsig" as the prefix for the name space for Digital Signatures.</p><p>Finally, the call to sig->createBlankSignature sets up both the DOM structure and the XSEC objects for a new signature with no <Reference> elements. In this case, the signature will be made using Commented C14n canonicalisation, and a HMAC-SHA1 signature.</p><p><strong>Warning:</strong> The XSECProvider class still "owns" the DSIGSignature object. To delete the object, the original provider.release(sig) call should be used. Never delete a DSIGSignature object directly.</p><h5 id="c_programming-CreateaReferenceandSign">Create a Reference and Sign</h5><p>Now that the signature object is create
d, the signature is inserted into the document, and a reference is created and set for an enveloping transform.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default">
// Insert the signature DOM nodes into the doc
rootElem->appendChild(doc->createTextNode(MAKE_UNICODE_STRING("\n")));
@@ -211,15 +169,8 @@ int main (int argc, char **argv) {
DSIGReference * ref = sig->createReference("");
ref->appendEnvelopedSignatureTransform();
</pre>
-</div></div>
-
-<p>The "" parameter to createReference sets the URI attribute for the reference to be "" - indicating the root element of the document in which the signature resides. The call to appendEnvelopedSignatureTransform adds a standard eneveloped-signature transform to the Reference node.</p>
-
-<p>The macro MAKE_UNICODE_STRING is defined within the library header files and is used to transcode local code page strings. There is no need to insert the reference object into the DOM structure. This is done automatically by the createReference call.</p>
-
-<p>Finally we create a signing key and sign the document.</p>
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">
+</div></div><p>The "" parameter to createReference sets the URI attribute for the reference to be "" - indicating the root element of the document in which the signature resides. The call to appendEnvelopedSignatureTransform adds a standard eneveloped-signature transform to the Reference node.</p><p>The macro MAKE_UNICODE_STRING is defined within the library header files and is used to transcode local code page strings. There is no need to insert the reference object into the DOM structure. This is done automatically by the createReference call.</p><p>Finally we create a signing key and sign the document.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default">
// Set the HMAC Key to be the string "secret"
OpenSSLCryptoKeyHMAC * hmacKey = new OpenSSLCryptoKeyHMAC();
@@ -242,19 +193,8 @@ int main (int argc, char **argv) {
}
</pre>
-</div></div>
-
-<p>The first two code lines create an OpenSSLCryptoKeyHMAC object, and set the key value to the string "secret". The OpenSSL... classes are the interface layer between XSEC and OpenSSL. More information can be found in the API documentation, but the main point of note is that the XSEC library never deals directly with OpenSSL - it works via the XSECCrypto abstract classes which are implemented in the OpenSSLCrypto code. This would allow another person to re-implement the XSECCrypto code to use any cryptographic provider required.</p>
-
-<p>Once the key is passed to the signature it is owned by the signature. The signature object will delete the key when it is itself deleted, or a new key is passed in.</p>
-
-<p>The call to sig->appendKeyName() is used to append a <KeyName> element into the <KeyInfo> block. The KeyInfo block was created as part of this call.</p>
-
-<p>After the call to sig->sign() the DOM structure has the correct hash and signature values. The owner program can write, store or further manipulate the document as required. If a document manipulation might affect the signature (in this case almost anything would, as we are using an enveloping transform which effectively signs everything that is not part of the signature), then a further call to sig->sign() will re-sign the changes.</p>
-
-<p>The last part of the code does some work to output the new DOM structure. The output should look something like the following:</p>
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;">
+</div></div><p>The first two code lines create an OpenSSLCryptoKeyHMAC object, and set the key value to the string "secret". The OpenSSL... classes are the interface layer between XSEC and OpenSSL. More information can be found in the API documentation, but the main point of note is that the XSEC library never deals directly with OpenSSL - it works via the XSECCrypto abstract classes which are implemented in the OpenSSLCrypto code. This would allow another person to re-implement the XSECCrypto code to use any cryptographic provider required.</p><p>Once the key is passed to the signature it is owned by the signature. The signature object will delete the key when it is itself deleted, or a new key is passed in.</p><p>The call to sig->appendKeyName() is used to append a <KeyName> element into the <KeyInfo> block. The KeyInfo block was created as part of this call.</p><p>After the call to sig->sign() the DOM structure has the correct hash and signature values. The owne
r program can write, store or further manipulate the document as required. If a document manipulation might affect the signature (in this case almost anything would, as we are using an enveloping transform which effectively signs everything that is not part of the signature), then a further call to sig->sign() will re-sign the changes.</p><p>The last part of the code does some work to output the new DOM structure. The output should look something like the following:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default">
<Letter>
<ToAddress>The address of the Recipient</ToAddress>
<FromAddress>The address of the Sender</FromAddress>
@@ -285,23 +225,8 @@ To whom it may concern
</ds:Signature>
</Letter>
</pre>
-</div></div>
-
-<p>Note that the DigestValue and SignatureValue elements have been filled in.</p>
-
-<h3 id="c_programming-Asimplevalidationexample">A simple validation example</h3>
-
-<p>The second example takes a pre-signed document and an associated certificate and verifies the embedded signature. The document in question is a simple purchase order, and changes are made to the value of the order to demonstrate a signature failing verification.</p>
-
-<h5 id="c_programming-Setup.1">Setup</h5>
-
-<p>As in the first example, Initialisation of the libraries is performed, and Xerces is used to read in the document (which in this case is stored in a string in the source code).</p>
-
-<p>In order to be able to modify the contents of the document later on, we also quickly find the string containing the value of the purchase order.</p>
-
-<p>For the sake of brevity, the code relating to parsing the in-memory document has been removed from the snippet below.</p>
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">
+</div></div><p>Note that the DigestValue and SignatureValue elements have been filled in.</p><h3 id="c_programming-Asimplevalidationexample">A simple validation example</h3><p>The second example takes a pre-signed document and an associated certificate and verifies the embedded signature. The document in question is a simple purchase order, and changes are made to the value of the order to demonstrate a signature failing verification.</p><h5 id="c_programming-Setup.1">Setup</h5><p>As in the first example, Initialisation of the libraries is performed, and Xerces is used to read in the document (which in this case is stored in a string in the source code).</p><p>In order to be able to modify the contents of the document later on, we also quickly find the string containing the value of the purchase order.</p><p>For the sake of brevity, the code relating to parsing the in-memory document has been removed from the snippet below.</p><div class="code panel pdl" style="border-width: 1px;"><
div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default">
int main (int argc, char **argv) {
try {
@@ -346,13 +271,8 @@ int main (int argc, char **argv) {
exit (1);
}
</pre>
-</div></div>
-
-<h5 id="c_programming-CreatetheSignatureandKeyobjects">Create the Signature and Key objects</h5>
-
-<p>Now that the document is in memory, an XSECProvider is created and used to create a new DSIGSignature object. In addition, the OpenSSL interface routines are used to read in a certificate and obtain the associated public key.</p>
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">
+</div></div><h5 id="c_programming-CreatetheSignatureandKeyobjects">Create the Signature and Key objects</h5><p>Now that the document is in memory, an XSECProvider is created and used to create a new DSIGSignature object. In addition, the OpenSSL interface routines are used to read in a certificate and obtain the associated public key.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default">
XSECProvider prov;
DSIGSignature * sig = prov.newSignatureFromDOM(doc);
@@ -366,24 +286,8 @@ int main (int argc, char **argv) {
sig->load();
</pre>
-</div></div>
-
-<p>In this case, the signature is create with the newSignatureFromDOM method. This tells the library that the signature structure (although not necessarily a signed structure) already exists in the DOM nodes. The library attempts to find the <Signature> node so that the load will work. (The library will throw an XSECException if it cannot find the Element.)</p>
-
-<p>The later call to sig->load() tells the library to read the DOM structure and create the appropriate DSIG elements.</p>
-
-<p>In this case an OpenSSLCryptoX509 object is also created. It is used to read in the cert string and convert to an X509 structure. This could also be done using standard calls directly to OpenSSL, but this is a quick shortcut.</p>
-
-<h5 id="c_programming-Findakey">Find a key</h5>
-
-<p>As we already know the key, the following code snippet loads the key directly from the related X509. However prior to doing this, the code demonstrates using the DSIGKeyInfo structures to find the key name that was embedded in the certificate. In an application, this could be used to reference the correct key to be passed in. (Maybe via an XKMS call.)</p>
-
-<p>the safeBuffer type is used extensively within the XSEC library to safely handle variable length strings and raw buffers. The call to rawCharBuffer() simply returns a (char *) type pointer to the buffer within the safeBuffer</p>
-
-<p>The call to clonePublicKey() returns a copy of the public key embedded in the certificate. It is owned by the caller, so in this case it can safely be passed to the DSIGSignature object where it will be destroyed when another key is loaded or the object is released by the XSECProvider.</p>
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">
+</div></div><p>In this case, the signature is create with the newSignatureFromDOM method. This tells the library that the signature structure (although not necessarily a signed structure) already exists in the DOM nodes. The library attempts to find the <Signature> node so that the load will work. (The library will throw an XSECException if it cannot find the Element.)</p><p>The later call to sig->load() tells the library to read the DOM structure and create the appropriate DSIG elements.</p><p>In this case an OpenSSLCryptoX509 object is also created. It is used to read in the cert string and convert to an X509 structure. This could also be done using standard calls directly to OpenSSL, but this is a quick shortcut.</p><h5 id="c_programming-Findakey">Find a key</h5><p>As we already know the key, the following code snippet loads the key directly from the related X509. However prior to doing this, the code demonstrates using the DSIGKeyInfo structures to find the key name tha
t was embedded in the certificate. In an application, this could be used to reference the correct key to be passed in. (Maybe via an XKMS call.)</p><p>the safeBuffer type is used extensively within the XSEC library to safely handle variable length strings and raw buffers. The call to rawCharBuffer() simply returns a (char *) type pointer to the buffer within the safeBuffer</p><p>The call to clonePublicKey() returns a copy of the public key embedded in the certificate. It is owned by the caller, so in this case it can safely be passed to the DSIGSignature object where it will be destroyed when another key is loaded or the object is released by the XSECProvider.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default">
DSIGKeyInfoList * kinfList = sig->getKeyInfoList();
// See if we can find a Key Name
@@ -400,13 +304,8 @@ int main (int argc, char **argv) {
sig->setSigningKey(x509->clonePublicKey());
</pre>
-</div></div>
-
-<h5 id="c_programming-Validatethesignature">Validate the signature</h5>
-
-<p>Finally the signature is validated. In this case, we validate it three times. First with the original DOM structure, then with the price changed and finally with the price set back to the original value.</p>
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">
+</div></div><h5 id="c_programming-Validatethesignature">Validate the signature</h5><p>Finally the signature is validated. In this case, we validate it three times. First with the original DOM structure, then with the price changed and finally with the price set back to the original value.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default">
cout << "Amount = " << amt << " -> ";
if (sig->verify()) {
@@ -438,39 +337,16 @@ int main (int argc, char **argv) {
cout << "Incorrect Signature\n";
}
</pre>
-</div></div>
-<p>When run, the program outputs the following:</p>
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;">
+</div></div><p>When run, the program outputs the following:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default">
Key Name = C=AU, ST=Vic, O=XML-Security-C Project,
CN=Samples Demo Certificate
Amount = $16.50 -> Signature Valid
Amount = $0.50 -> Incorrect Signature
Amount = $16.50 -> Signature Valid
</pre>
-</div></div>
-
-<h1 id="c_programming-XMLEncryptionProgramming">XML Encryption Programming</h1>
-
-<h3 id="c_programming-Overview.1">Overview</h3>
-
-<p>As with signatures, there are two main modes of operation for the library when performing encryption functions - Encryption and Decryption. Decryption is generally fairly simple, as the library will handle most of the work around de-referencing key material and re-creating a DOM document (or returning a byte stream).</p>
-
-<p>Encryption is fairly simple if you are trying to encrypt a DOM structure. The library will encrypt the nodes and then replace them with the encrypted version. However if you want to embed an arbitrary encrypted object in the document, you will need to encrypt it first and then pass the encrypted text into the library.</p>
-
-<p>The rest of this page looks at some simple examples around encrypting and decrypting nodes within an XML document</p>
-
-<h3 id="c_programming-Asimpleencryptionexample">A simple encryption example</h3>
-
-<p>The next example encrypts an element (and all its children) from a pre-generated document. It uses a randomly generated key to handle the bulk encryption, and then encrypts this using an RSA public key. The resultant encrypted key is embedded in an <EncryptedKey> element.</p>
-
-<p>This example can be found in the src/samples directory as simpleEncrypt.cpp.</p>
-
-<h5 id="c_programming-Setup.2">Setup</h5>
-
-<p>The first step is initialisation of Xerces, Xalan (if used) and XML-Security. Once this is done, we create a document. For brevity, the details of the call to createLetter are not included on this page. The function is very simple - it creates an XML DOM document that represents a letter, and sets a global variable (g_toEncrypt) that will be used later on to determine what node to encrypt.</p>
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">
+</div></div><h1 id="c_programming-XMLEncryptionProgramming">XML Encryption Programming</h1><h3 id="c_programming-Overview.1">Overview</h3><p>As with signatures, there are two main modes of operation for the library when performing encryption functions - Encryption and Decryption. Decryption is generally fairly simple, as the library will handle most of the work around de-referencing key material and re-creating a DOM document (or returning a byte stream).</p><p>Encryption is fairly simple if you are trying to encrypt a DOM structure. The library will encrypt the nodes and then replace them with the encrypted version. However if you want to embed an arbitrary encrypted object in the document, you will need to encrypt it first and then pass the encrypted text into the library.</p><p>The rest of this page looks at some simple examples around encrypting and decrypting nodes within an XML document</p><h3 id="c_programming-Asimpleencryptionexample">A simple encryption example</h3><p>The n
ext example encrypts an element (and all its children) from a pre-generated document. It uses a randomly generated key to handle the bulk encryption, and then encrypts this using an RSA public key. The resultant encrypted key is embedded in an <EncryptedKey> element.</p><p>This example can be found in the src/samples directory as simpleEncrypt.cpp.</p><h5 id="c_programming-Setup.2">Setup</h5><p>The first step is initialisation of Xerces, Xalan (if used) and XML-Security. Once this is done, we create a document. For brevity, the details of the call to createLetter are not included on this page. The function is very simple - it creates an XML DOM document that represents a letter, and sets a global variable (g_toEncrypt) that will be used later on to determine what node to encrypt.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default">
int main (int argc, char **argv) {
try {
@@ -496,15 +372,8 @@ int main (int argc, char **argv) {
// Create a letter
DOMDocument *doc = createLetter(impl);
</pre>
-</div></div>
-
-<h5 id="c_programming-SetupforEncryption">Setup for Encryption</h5>
-
-<p>Once the library is initialised, we create a XENCCipher object in a manner similar to the creation of a DSIGSignature object. The XENCCipher object is used to actually perform encryption/decryption functions and to manipulate the various encryption objects provided by the library.</p>
-
-<p>As well as creating the XENCCipher object, the sample uses the RAND_bytes function within the <strong>OpenSSL</strong> library to create a random key that will be used during the encryption process.</p>
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">
+</div></div><h5 id="c_programming-SetupforEncryption">Setup for Encryption</h5><p>Once the library is initialised, we create a XENCCipher object in a manner similar to the creation of a DSIGSignature object. The XENCCipher object is used to actually perform encryption/decryption functions and to manipulate the various encryption objects provided by the library.</p><p>As well as creating the XENCCipher object, the sample uses the RAND_bytes function within the <strong>OpenSSL</strong> library to create a random key that will be used during the encryption process.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default">
try {
/* Create the cipher object that we need */
@@ -534,21 +403,8 @@ int main (int argc, char **argv) {
}
</pre>
-</div></div>
-
-<h5 id="c_programming-EncryptionofElement">Encryption of Element</h5>
-
-<p>The actual code to perform encryption is very small. Most of the complexity for standard encryption is hidden within the library.</p>
-
-<p>The first two lines of code wrap the generated key bytes in an OpenSSL 3DES key. This is then passed into the cipher object with a call to setKey(key).</p>
-
-<p>The last line in the following block performs the actual encryption. the first parameter to cipher->encryptElement is the node that will be encrypted. The second is the algorithm to be used. This is used to calcualte the Algorithm URI to be set in the <EncryptedData> element.</p>
-
-<p>This call to EncryptElement will encrypt the provided element using the key set previously. The passed in element will be replaced with an <EncryptedData> element containing the encrypted version of the element and all its children.</p>
-
-<p>If no further information is required to be embedded in the <EncryptedData> structure (such as <KeyInfo> nodes), the usage of the library could be terminated here.</p>
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">
+</div></div><h5 id="c_programming-EncryptionofElement">Encryption of Element</h5><p>The actual code to perform encryption is very small. Most of the complexity for standard encryption is hidden within the library.</p><p>The first two lines of code wrap the generated key bytes in an OpenSSL 3DES key. This is then passed into the cipher object with a call to setKey(key).</p><p>The last line in the following block performs the actual encryption. the first parameter to cipher->encryptElement is the node that will be encrypted. The second is the algorithm to be used. This is used to calcualte the Algorithm URI to be set in the <EncryptedData> element.</p><p>This call to EncryptElement will encrypt the provided element using the key set previously. The passed in element will be replaced with an <EncryptedData> element containing the encrypted version of the element and all its children.</p><p>If no further information is required to be embedded in the <EncryptedData>
structure (such as <KeyInfo> nodes), the usage of the library could be terminated here.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default">
/* Wrap this in a Symmetric 3DES key */
OpenSSLCryptoSymmetricKey * key =
@@ -559,21 +415,8 @@ int main (int argc, char **argv) {
/* Encrypt the element that needs to be hidden */
cipher->encryptElement(g_toEncrypt, ENCRYPT_3DES_CBC);
</pre>
-</div></div>
-
-<h5 id="c_programming-Createan<EncryptedKey>">Create an <EncryptedKey></h5>
-
-<p>The following snippet of code uses the previously created XENCCipher object to encrypt the pseudo random key using an RSA key loaded from a X.509 certificate.</p>
-
-<p>The first two lines load the certificate into an OpenSSLCryptoX509 structure, which is then used to extract the public key from the certificate and pass into the cipher.</p>
-
-<p>A call to setKEK is used rather than setKey. This call is used to tell the cipher object that the key being used is a Key Encryption Key, and should be used for encrypting/decrypting <EncryptedKey> elements.</p>
-
-<p>The final line actually performs the encryption and created the <EncryptedKey> structure. The first two parameters define the buffer and its length to be encrypted. The last defines the encryption algorithm to be used.</p>
-
-<p>The encryptedKey method returns an XENCEncryptedKey object. This contains the DOM structure for the object, but it is not yet rooted in a particular document. (Although it is created using the DOMDocument that was passed in during the call to newCipher.)</p>
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">
+</div></div><h5 id="c_programming-Createan<EncryptedKey>">Create an <EncryptedKey></h5><p>The following snippet of code uses the previously created XENCCipher object to encrypt the pseudo random key using an RSA key loaded from a X.509 certificate.</p><p>The first two lines load the certificate into an OpenSSLCryptoX509 structure, which is then used to extract the public key from the certificate and pass into the cipher.</p><p>A call to setKEK is used rather than setKey. This call is used to tell the cipher object that the key being used is a Key Encryption Key, and should be used for encrypting/decrypting <EncryptedKey> elements.</p><p>The final line actually performs the encryption and created the <EncryptedKey> structure. The first two parameters define the buffer and its length to be encrypted. The last defines the encryption algorithm to be used.</p><p>The encryptedKey method returns an XENCEncryptedKey object. This contains the DOM structure for the obj
ect, but it is not yet rooted in a particular document. (Although it is created using the DOMDocument that was passed in during the call to newCipher.)</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default">
/* Now lets create an EncryptedKey element to hold the generated key */
/* First lets load the public key in the certificate */
@@ -589,13 +432,8 @@ int main (int argc, char **argv) {
XENCEncryptedKey * encryptedKey =
cipher->encryptKey(keyBuf, 24, ENCRYPT_RSA_15);
</pre>
-</div></div>
-
-<h5 id="c_programming-Append<EncryptedKey>to<EncryptedData>">Append <EncryptedKey> to <EncryptedData></h5>
-
-<p>The final part (other than outputting the result) is to retrieve the <EncryptedData> element that was previously created and append the newly created <EncryptedKey> as a <KeyInfo> element.</p>
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">
+</div></div><h5 id="c_programming-Append<EncryptedKey>to<EncryptedData>">Append <EncryptedKey> to <EncryptedData></h5><p>The final part (other than outputting the result) is to retrieve the <EncryptedData> element that was previously created and append the newly created <EncryptedKey> as a <KeyInfo> element.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default">
/*
* Add the encrypted Key to the previously created EncryptedData, which
* we first retrieve from the cipher object. This will automatically create
@@ -605,10 +443,8 @@ int main (int argc, char **argv) {
XENCEncryptedData * encryptedData = cipher->getEncryptedData();
encryptedData->appendEncryptedKey(encryptedKey);
</pre>
-</div></div>
-<p>The above code results in a document that contains the newly created <EncryptedData> as follows:</p>
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;">
+</div></div><p>The above code results in a document that contains the newly created <EncryptedData> as follows:</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default">
<Letter>
<ToAddress>The address of the Recipient</ToAddress>
<FromAddress>The address of the Sender</FromAddress>
@@ -634,27 +470,8 @@ R87TzroBYsYwfHmXmrKHL9K9sB6zmuec1TjVzm2c
</xenc:CipherData>
</xenc:EncryptedData></Letter>
</pre>
-</div></div>
-
-<h3 id="c_programming-Asimpledecryptionexample">A simple decryption example</h3>
-
-<p>The final example shows how to use the library to decrypt an EncryptedData structure. A private key is loaded as a Key Encryption Key (KEK), and a call is made to the library which decrypts the encrypted data and inserts the resulting DOM nodes back into the original document.</p>
-
-<p>This example can be found in the src/samples directory as simpleDecrypt.cpp.</p>
-
-<h5 id="c_programming-Setup.3">Setup</h5>
-
-<p>The setup process is much the same as for simpleVerify. The document (which is the document created in simpleEncrypt) is parsed using Xerces and a DOMDocument is returned.</p>
-
-<h5 id="c_programming-LoadPrivateKey">Load Private Key</h5>
-
-<p>The simpleDecrypt uses a preloaded RSA private key for the decryption. A key resolver (XSECKeyInfoResolver) can also be used to provide a callback mechanism such that applications can determine the correct key at run time.</p>
-
-<p>The following code uses a XSECProvider to obtain a XENCCipheruses OpenSSL to load the private key from the s_privateKey char array.</p>
-
-<p>The key is loaded using a call to setKEK. This method loads the key as a Key Encryption Key - which means it will be used to decrypt an <EncryptedKey> structure.</p>
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">
+</div></div><h3 id="c_programming-Asimpledecryptionexample">A simple decryption example</h3><p>The final example shows how to use the library to decrypt an EncryptedData structure. A private key is loaded as a Key Encryption Key (KEK), and a call is made to the library which decrypts the encrypted data and inserts the resulting DOM nodes back into the original document.</p><p>This example can be found in the src/samples directory as simpleDecrypt.cpp.</p><h5 id="c_programming-Setup.3">Setup</h5><p>The setup process is much the same as for simpleVerify. The document (which is the document created in simpleEncrypt) is parsed using Xerces and a DOMDocument is returned.</p><h5 id="c_programming-LoadPrivateKey">Load Private Key</h5><p>The simpleDecrypt uses a preloaded RSA private key for the decryption. A key resolver (XSECKeyInfoResolver) can also be used to provide a callback mechanism such that applications can determine the correct key at run time.</p><p>The following code uses a XS
ECProvider to obtain a XENCCipheruses OpenSSL to load the private key from the s_privateKey char array.</p><p>The key is loaded using a call to setKEK. This method loads the key as a Key Encryption Key - which means it will be used to decrypt an <EncryptedKey> structure.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default">
XSECProvider prov;
XENCCipher *cipher;
@@ -670,30 +487,16 @@ R87TzroBYsYwfHmXmrKHL9K9sB6zmuec1TjVzm2c
OpenSSLCryptoKeyRSA * k = new OpenSSLCryptoKeyRSA(pk);
cipher->setKEK(k);
</pre>
-</div></div>
-
-<h5 id="c_programming-PerformDecryption">Perform Decryption</h5>
-
-<p>Now that the key is loaded, the actual decryption is performed using two lines of code. The first finds the node to be decrypted. In this case, the findXENCNode library function is used.</p>
-
-<p>The second line, decryptElement actually performs the decryption. It performs the following steps :</p>
-
-<ul><li>Load the <EncryptedData> structure into an XENCEncryptedData structure.</li><li>if no decryption key is loaded (in this case, none is), search the <KeyInfo> list for an <EncryptedKey> element (one will be found in this case).</li><li>Use the previously loaded KEK to decrypt the key found in the previous step.</li><li>Use the decrypted key to decrypt the <EncryptedData> data</li><li>Parse the decrypted data into DOM nodes</li><li>Replace the <EncryptedData> with the DOM fragment returned in the previous step</li></ul>
-
-
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: java; gutter: false; theme: Default" style="font-size:12px;">
+</div></div><h5 id="c_programming-PerformDecryption">Perform Decryption</h5><p>Now that the key is loaded, the actual decryption is performed using two lines of code. The first finds the node to be decrypted. In this case, the findXENCNode library function is used.</p><p>The second line, decryptElement actually performs the decryption. It performs the following steps :</p><ul><li>Load the <EncryptedData> structure into an XENCEncryptedData structure.</li><li>if no decryption key is loaded (in this case, none is), search the <KeyInfo> list for an <EncryptedKey> element (one will be found in this case).</li><li>Use the previously loaded KEK to decrypt the key found in the previous step.</li><li>Use the decrypted key to decrypt the <EncryptedData> data</li><li>Parse the decrypted data into DOM nodes</li><li>Replace the <EncryptedData> with the DOM fragment returned in the previous step</li></ul><div class="code panel pdl" style="border-width: 1px;"><div cl
ass="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default">
/* Find the EncryptedData node */
DOMNode * encryptedNode = findXENCNode(doc, "EncryptedData");
/* Do the decrypt */
cipher->decryptElement((DOMElement *) encryptedNode);
</pre>
-</div></div>
-
-<p>The result of these steps is the decrypted letter.</p>
-<div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
-<pre class="brush: xml; gutter: false; theme: Default" style="font-size:12px;">
+</div></div><p>The result of these steps is the decrypted letter.</p><div class="code panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+<pre class="brush: java; gutter: false; theme: Default">
<Letter>
<ToAddress>The address of the Recipient</ToAddress>
<FromAddress>The address of the Sender</FromAddress>
@@ -704,9 +507,7 @@ To whom it may concern, my secret credit
...
</Text></Letter>
</pre>
-</div></div>
-
-</div>
+</div></div></div>
</div>
<!-- Content -->
</td>
Modified: websites/production/santuario/content/creleasenotes.html
==============================================================================
--- websites/production/santuario/content/creleasenotes.html (original)
+++ websites/production/santuario/content/creleasenotes.html Thu Jun 28 10:52:08 2018
@@ -99,7 +99,7 @@ Apache Santuario -- c_release_notes
<td height="100%">
<!-- Content -->
<div class="wiki-content">
-<div id="ConfluenceContent"><h1 id="c_release_notes-ApacheXMLSecurityforC++ReleaseNotes">Apache XML Security for C++ Release Notes</h1><h3 id="c_release_notes-CurrentReleases">Current Releases</h3><ul><li><a shape="rect" class="external-link" href="https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311231&version=12329355">Apache XML Security for C++ 1.7.3</a></li></ul><h3 id="c_release_notes-Olderreleases">Older releases</h3><ul><li><a shape="rect" class="external-link" href="https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311231&version=12324648">Apache XML Security for C++ 1.7.2</a></li><li><a shape="rect" class="external-link" href="https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311231&version=12324376">Apache XML Security for C++ 1.7.1</a></li><li><a shape="rect" class="external-link" href="https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311231&version=12321856">Apache XML Security for C++
1.7.0</a></li><li><a shape="rect" class="external-link" href="https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311231&version=12316452">Apache XML Security for C++ 1.6.1</a></li><li><a shape="rect" class="external-link" href="https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311231&version=12315941">Apache XML Security for C++ 1.6.0</a></li><li><a shape="rect" href="c151releasenotes.html">Apache XML Security for C++ 1.5.1</a></li><li><a shape="rect" href="c150releasenotes.html">Apache XML Security for C++ 1.5.0</a></li><li><a shape="rect" href="c140releasenotes.html">Apache XML Security for C++ 1.4.0</a></li><li><a shape="rect" href="c131releasenotes.html">Apache XML Security for C++ 1.3.1</a></li><li><a shape="rect" href="c130releasenotes.html">Apache XML Security for C++ 1.3.0</a></li><li><a shape="rect" href="c121releasenotes.html">Apache XML Security for C++ 1.2.1</a></li><li><a shape="rect" href="c120releasenotes.html">Apache XML Secu
rity for C++ 1.2.0</a></li><li><a shape="rect" href="c11releasenotes.html">Apache XML Security for C++ 1.1</a></li><li><a shape="rect" href="c10releasenotes.html">Apache XML Security for C++ 1.0</a></li></ul></div>
+<div id="ConfluenceContent"><h1 id="c_release_notes-ApacheXMLSecurityforC++ReleaseNotes">Apache XML Security for C++ Release Notes</h1><h3 id="c_release_notes-CurrentReleases">Current Releases</h3><ul><li><a shape="rect" class="external-link" href="https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311231&version=12341551">Apache XML Security for C++ 2.0.0</a><ul><li>As a major update, this release includes a variety and small and slightly less-small changes that are not reflected in the release notes above.</li></ul></li></ul><h3 id="c_release_notes-Olderreleases">Older releases</h3><ul><li><a shape="rect" class="external-link" href="https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311231&version=12329355">Apache XML Security for C++ 1.7.3</a></li><li><a shape="rect" class="external-link" href="https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311231&version=12324648">Apache XML Security for C++ 1.7.2</a></li><li><a sha
pe="rect" class="external-link" href="https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311231&version=12324376">Apache XML Security for C++ 1.7.1</a></li><li><a shape="rect" class="external-link" href="https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311231&version=12321856">Apache XML Security for C++ 1.7.0</a></li><li><a shape="rect" class="external-link" href="https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311231&version=12316452">Apache XML Security for C++ 1.6.1</a></li><li><a shape="rect" class="external-link" href="https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12311231&version=12315941">Apache XML Security for C++ 1.6.0</a></li><li><a shape="rect" href="c151releasenotes.html">Apache XML Security for C++ 1.5.1</a></li><li><a shape="rect" href="c150releasenotes.html">Apache XML Security for C++ 1.5.0</a></li><li><a shape="rect" href="c140releasenotes.html">Apache XML Security for C++ 1.4.
0</a></li><li><a shape="rect" href="c131releasenotes.html">Apache XML Security for C++ 1.3.1</a></li><li><a shape="rect" href="c130releasenotes.html">Apache XML Security for C++ 1.3.0</a></li><li><a shape="rect" href="c121releasenotes.html">Apache XML Security for C++ 1.2.1</a></li><li><a shape="rect" href="c120releasenotes.html">Apache XML Security for C++ 1.2.0</a></li><li><a shape="rect" href="c11releasenotes.html">Apache XML Security for C++ 1.1</a></li><li><a shape="rect" href="c10releasenotes.html">Apache XML Security for C++ 1.0</a></li></ul></div>
</div>
<!-- Content -->
</td>