blautenb 2004/02/29 03:31:15
Modified: doc/site/src/documentation/content/xdocs index.xml site.xml
doc/site/src/documentation/content/xdocs/c faq.xml index.xml
programming.xml releases.xml tools.xml
Added: doc/site/src/documentation/content/xdocs/c prog_enc.xml
Log:
First cut at C++ 1.1 docs
Revision Changes Path
1.6 +13 -0
xml-security/doc/site/src/documentation/content/xdocs/index.xml
Index: index.xml
===================================================================
RCS file:
/home/cvs/xml-security/doc/site/src/documentation/content/xdocs/index.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- index.xml 9 Aug 2003 12:02:33 -0000 1.5
+++ index.xml 29 Feb 2004 11:31:15 -0000 1.6
@@ -7,6 +7,19 @@
<body>
<section>
<title>News</title>
+ <section>
+ <title>March 2004</title>
+ <p>
+ Version 1.1 of the C++ library has been released. Supporting
+ Xerces 2.5, 2.4 and 2.3 together with Xalan 1.6 and 1.7, this
+ version provides :
+ </p>
+ <ul>
+ <li>Beta implementation of XML Encryption</li>
+ <li>Improved support for Windows Crypto API</li>
+ <li>Bug fixes to Signature implementation</li>
+ </ul>
+ </section>
<section>
<title>August 2003</title>
<p>
1.5 +5 -1
xml-security/doc/site/src/documentation/content/xdocs/site.xml
Index: site.xml
===================================================================
RCS file:
/home/cvs/xml-security/doc/site/src/documentation/content/xdocs/site.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- site.xml 31 Aug 2003 01:06:56 -0000 1.4
+++ site.xml 29 Feb 2004 11:31:15 -0000 1.5
@@ -41,7 +41,6 @@
<c label="C++" href="c/" tab="cpp">
<index label="Index" href="index.html"/>
<install label="Installation" href="installation.html"/>
- <programming label="Programming" href="programming.html"/>
<cfaq label="FAQs" href="faq.html"/>
<external label="API Docs" href="apiDocs/index.html"/>
<external label="Nightly API build"
href="http://nagoya.apache.org/~blautenb/xml-security-c/apiDocs/"/>
@@ -50,6 +49,11 @@
<credits label="Credits" href="credits.html"/>
<interop label="Interoperability" href="interop.html"/>
</c>
+
+ <cprog label="Programming" href="c/" tab="cpp">
+ <signature label="Signatures" href="programming.html"/>
+ <enc label="Encryption" href="prog_enc.html"/>
+ </cprog>
<references label="References">
<xmldsig label="W3C XML DSig" href="http://www.w3c.org/Signature"/>
1.5 +38 -1
xml-security/doc/site/src/documentation/content/xdocs/c/faq.xml
Index: faq.xml
===================================================================
RCS file:
/home/cvs/xml-security/doc/site/src/documentation/content/xdocs/c/faq.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- faq.xml 20 Nov 2003 09:03:41 -0000 1.4
+++ faq.xml 29 Feb 2004 11:31:15 -0000 1.5
@@ -14,7 +14,7 @@
<answer>
<p>
The main development work for the library is done using
OpenSSL, so
- this is the recommended option. However, a developmental
Windows
+ this is the recommended option. However, a Windows
Crypto API interface is also now provided.
</p>
<p>
@@ -111,6 +111,43 @@
form of SignedInfo will be different to that generated during
<code>sign()</code>.
</p>
+ </answer>
+ </faq>
+ <faq id="ids">
+ <question>
+ How does the library identify Id attributes?
+ </question>
+ <answer>
+ <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
+ <em>DOMDocument::getElementById()</em>. 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 this is a potential security exposure, this behaviour can
be
+ disabled using a call to
+ <em>DISGSignatures::setIdByAttributeName(false)</em>. 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>
+ <warning>
+ In version 1.1, 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.
+ </warning>
</answer>
</faq>
</part>
1.6 +30 -17
xml-security/doc/site/src/documentation/content/xdocs/c/index.xml
Index: index.xml
===================================================================
RCS file:
/home/cvs/xml-security/doc/site/src/documentation/content/xdocs/c/index.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- index.xml 9 Aug 2003 12:02:33 -0000 1.5
+++ index.xml 29 Feb 2004 11:31:15 -0000 1.6
@@ -6,26 +6,19 @@
</header>
<body>
- <section>
- <title>News - August 2003</title>
- <p>
- Version 1.00 of the library has now been released. It features
:
+ <section>
+ <title>News - March 2004</title>
+ <p>
+ Version 1.1 of the C++ library has been released. Supporting
+ Xerces 2.5, 2.4 and 2.3 together with Xalan 1.6 and 1.7, this
+ version provides :
</p>
<ul>
- <li>the first stable release</li>
- <li>full implementation of all mandatory requirements of
DSIG</li>
- <li>implementation of canonicalised XML</li>
- <li>implementation of exclusive-canonicalised XML</li>
- <li>implementation of XPath-filter</li>
- <li>FreeBSD, NetBSD and Cygwin builds</li>
+ <li>Beta implementation of XML Encryption</li>
+ <li>Improved support for Windows Crypto API</li>
+ <li>Bug fixes to Signature implementation</li>
</ul>
- <p>
- Version 1.00 is has been tested with Xerces-C v2.2 and the
newly
- released Xalan-C v1.6. Xerces-C v2.3 is also supported. Note
that
- versions of Xalan prior to v1.6 are not supported (due to the
new
- changed location of include files).
- </p>
- </section>
+ </section>
<section>
<title>Overview of the C++ Library</title>
<p>
@@ -83,6 +76,26 @@
<li>XPath Filter (to be added in next point release)</li>
<li>XML Encryption (to be added post 1.00 release)</li>
</ul>
+ </section>
+ <section>
+ <title>News - August 2003</title>
+ <p>
+ Version 1.00 of the library has now been released. It
features :
+ </p>
+ <ul>
+ <li>the first stable release</li>
+ <li>full implementation of all mandatory requirements of
DSIG</li>
+ <li>implementation of canonicalised XML</li>
+ <li>implementation of exclusive-canonicalised XML</li>
+ <li>implementation of XPath-filter</li>
+ <li>FreeBSD, NetBSD and Cygwin builds</li>
+ </ul>
+ <p>
+ Version 1.00 is has been tested with Xerces-C v2.2 and the
newly
+ released Xalan-C v1.6. Xerces-C v2.3 is also supported.
Note that
+ versions of Xalan prior to v1.6 are not supported (due to the
new
+ changed location of include files).
+ </p>
</section>
</section>
</body>
1.4 +5 -243
xml-security/doc/site/src/documentation/content/xdocs/c/programming.xml
Index: programming.xml
===================================================================
RCS file:
/home/cvs/xml-security/doc/site/src/documentation/content/xdocs/c/programming.xml,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- programming.xml 3 Feb 2004 11:06:07 -0000 1.3
+++ programming.xml 29 Feb 2004 11:31:15 -0000 1.4
@@ -3,16 +3,16 @@
<document>
<header>
- <title>Programming</title>
+ <title>XML Signature Programming</title>
</header>
<body>
<section>
<title>Overview</title>
<p>
- There are two main 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.
+ 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
@@ -477,244 +477,6 @@
Amount = $16.50 -> Signature Valid
]]></source>
</section>
- </section>
- <section id="simpleencrypt">
- <title>A simple encryption example</title>
- <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
- <em>simpleEncrypt.cpp</em>.
- </p>
- <section>
- <title>Setup</title>
- <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 <em>createLetter</em> 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 (<em>g_toEncrypt</em>) that will be used later on to
- determine what node to encrypt.
- </p>
- <source><![CDATA[
-int main (int argc, char **argv) {
-
- try {
- XMLPlatformUtils::Initialize();
-#ifndef XSEC_NO_XALAN
- XalanTransformer::initialize();
-#endif
- XSECPlatformUtils::Initialise();
- }
- catch (const XMLException &e) {
-
- cerr << "Error during initialisation of Xerces" << endl;
- cerr << "Error Message = : "
- << e.getMessage() << endl;
-
- }
-
- // Create a blank Document
-
- DOMImplementation *impl =
-
DOMImplementationRegistry::getDOMImplementation(MAKE_UNICODE_STRING("Core"));
-
- // Create a letter
- DOMDocument *doc = createLetter(impl);
- ]]></source>
- </section>
- <section>
- <title>Setup for Encryption</title>
- <p>
- Once the library is initialised, we create a
<em>XENCCipher</em>
- object in a manner similar to the creation of a
- <em>DSIGSignature</em> object. The <em>XENCCipher</em> 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 <em>XENCCipher</em> object, the sample
- uses the <em>RAND_bytes</em> function within the
- <strong>OpenSSL</strong>
- library to create a random key that will be used during the
- encryption process.
- </p>
- <source><![CDATA[
- try {
-
- /* Create the cipher object that we need */
-
- XSECProvider prov;
- XENCCipher *cipher;
-
- cipher = prov.newCipher(doc);
-
- /* Now generate a random key that we can use to encrypt the element
- *
- * First check the status of the random generation in OpenSSL
- */
-
- if (RAND_status() != 1) {
-
- cerr << "OpenSSL random generation not properly initialised" <<
endl;
- exit(1);
-
- }
-
- unsigned char keyBuf[24];
- if (RAND_bytes(keyBuf, 24) == 0) {
-
- cerr << "Error obtaining 24 bytes of random from OpenSSL" <<
endl;
- exit(1);
-
- }
-]]></source>
- </section>
- <section>
- <title>Encryption of Element</title>
- <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
<em>cipher</em>
- object with a call to <em>setKey(key)</em>.
- </p>
- <p>
- The last line in the following block performs the actual
encryption.
- the first parameter to <em>cipher->encryptElement</em> 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 <em>EncryptElement</em> 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>
- <source><![CDATA[
- /* Wrap this in a Symmetric 3DES key */
-
- OpenSSLCryptoSymmetricKey * key =
- new
OpenSSLCryptoSymmetricKey(XSECCryptoSymmetricKey::KEY_3DES_192);
- key->setKey(keyBuf, 24);
- cipher->setKey(key);
-
- /* Encrypt the element that needs to be hidden */
- cipher->encryptElement(g_toEncrypt, ENCRYPT_3DES_CBC);
-]]></source>
- </section>
- <section>
- <title>Create an <EncryptedKey></title>
- <p>
- The following snippet of code uses the previously created
- <em>XENCCipher</em> 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 <em>setKEK</em> is used rather than <em>setKey</em>.
- 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 <em>encryptedKey</em> method returns an
<em>XENCEncryptedKey</em>
- 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 <em>DOMDocument</em> that was passed in during the
call
- to <em>newCipher</em>.)
- </p>
- <source><![CDATA[
- /* Now lets create an EncryptedKey element to hold the generated key
*/
-
- /* First lets load the public key in the certificate */
- OpenSSLCryptoX509 * x509 = new OpenSSLCryptoX509();
- x509->loadX509Base64Bin(cert, strlen(cert));
-
- /* Now set the Key Encrypting Key (NOTE: Not the normal key) */
- cipher->setKEK(x509->clonePublicKey());
-
-
- /* Now do the encrypt, using RSA with PKCS 1.5 padding */
-
- XENCEncryptedKey * encryptedKey =
- cipher->encryptKey(keyBuf, 24, ENCRYPT_RSA_15);
-]]></source>
- </section>
- <section>
- <title>Append <EncryptedKey> to
<EncryptedData></title>
- <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>
-<source><![CDATA[
- /*
- * Add the encrypted Key to the previously created EncryptedData,
which
- * we first retrieve from the cipher object. This will
automatically create
- * the appropriate <KeyInfo> element within the EncryptedData
- */
-
- XENCEncryptedData * encryptedData = cipher->getEncryptedData();
- encryptedData->appendEncryptedKey(encryptedKey);
-]]></source>
- </section>
- <p>
- The above code results in a document that contains the newly
created
- <EncryptedData> as follows:
- </p>
-<source><![CDATA[
-<Letter>
-<ToAddress>The address of the Recipient</ToAddress>
-<FromAddress>The address of the Sender</FromAddress>
-<xenc:EncryptedData Type="http://www.w3.org/2001/04/xmlenc#Element";
-xmlns:xenc="http://www.w3.org/2001/04/xmlenc#";>
-<xenc:EncryptionMethod
Algorithm="http://www.w3.org/2001/04/xmlenc#tripledes-cbc"/>
-<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#";>
-<xenc:EncryptedKey xmlns:xenc="http://www.w3.org/2001/04/xmlenc#";>
-<xenc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/>
-<xenc:CipherData>
-<xenc:CipherValue>Wh8pAkDsQceHiktGxnlhXGfEMPDOLB6FwWp8PLedFEB3L3F6xHUoCOerIvA7Pgvv
-VYzVqLv4a5x5YdnCqikkFBLE/fruAUe2Z8ZTEn/CaPYmpzU6qYHALCl7Q61LcbqH
-R87TzroBYsYwfHmXmrKHL9K9sB6zmuec1TjVzm2c/Xs=
-</xenc:CipherValue>
-</xenc:CipherData>
-</xenc:EncryptedKey>
-</ds:KeyInfo>
-<xenc:CipherData>
-<xenc:CipherValue>YhqQciiFkLG1z0I1TJC6Pewnzw/gmVuGqcTvHtWpgak/b3NQDRAlv07lJOmBLoHX
-23LQ1CdPSxvnyerlJGwkY6xJ0M5tjpDregTVcECXo/bd+x8eIsF2kaawoZGCqD1K
-96T36Fx9rHek9bY/Hp1OiQ==
-</xenc:CipherValue>
-</xenc:CipherData>
-</xenc:EncryptedData></Letter>
-]]></source>
</section>
</body>
</document>
1.5 +22 -1
xml-security/doc/site/src/documentation/content/xdocs/c/releases.xml
Index: releases.xml
===================================================================
RCS file:
/home/cvs/xml-security/doc/site/src/documentation/content/xdocs/c/releases.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- releases.xml 23 Jun 2003 10:02:04 -0000 1.4
+++ releases.xml 29 Feb 2004 11:31:15 -0000 1.5
@@ -13,7 +13,28 @@
various releases of the library
</p>
<section>
- <title>Version 1.00</title>
+ <title>Version 1.1.0</title>
+ <p>
+ Version 1.1 provides bug fixes to signature functionality +
+ beta support for XML Encryption.
+ </p>
+ <p>
+ Changes from version 1.0.0 include :
+ </p>
+ <ul>
+ <li>Beta implementation of XML Encryption, using an interface
+ similar to that used in the Apache Java xml-security
library</li>
+ <li>Fix for bug where large text elements would be truncated
during
+ canonicalisation</li>
+ <li>Provision of a <em>cipher</em> tool that can be used to
encrypt
+ and decrypt XML documents</li>
+ <li>Updated and improved the Windows Crypto API interface</li>
+ <li>Other bug fixes to signature functionality</li>
+ <li>Updated to support Xerces 2.4/2.5 and Xalan 1.7</li>
+ </ul>
+ </section>
+ <section>
+ <title>Changes from 0.10 - 1.00</title>
<p>
Version 1.00 is the first release of the library considered
basically
stable. The interface is fairly simple, but all the mandatory
1.3 +2 -0
xml-security/doc/site/src/documentation/content/xdocs/c/tools.xml
Index: tools.xml
===================================================================
RCS file:
/home/cvs/xml-security/doc/site/src/documentation/content/xdocs/c/tools.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- tools.xml 5 May 2003 12:31:09 -0000 1.2
+++ tools.xml 29 Feb 2004 11:31:15 -0000 1.3
@@ -34,6 +34,8 @@
<li><em>siginf</em> - A tool to read in an XML Signature and
dump
various details about the signature and references to the
terminal
</li>
+ <li><em>cipher</em> - A tool to encrypt and decrypt XML
documents.
+ </li>
</ul>
<p>
The tools can all be run with no command line arguments to see
their
1.1
xml-security/doc/site/src/documentation/content/xdocs/c/prog_enc.xml
Index: prog_enc.xml
===================================================================
<?xml version="1.0"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN"
"document-v11.dtd">
<document>
<header>
<title>XML Encryption Programming</title>
</header>
<body>
<section id="overview">
<title>Overview</title>
<warning>
The Encryption functionality within the library is currently
beta.
Whilst the API is considered fairly functional, it may change in
version 1.2 as a result of feedback received from version 1.1.
</warning>
<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>
</section>
<section id="simpleencrypt">
<title>A simple encryption example</title>
<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
<em>simpleEncrypt.cpp</em>.
</p>
<section>
<title>Setup</title>
<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 <em>createLetter</em> 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 (<em>g_toEncrypt</em>) that will be used later on to
determine what node to encrypt.
</p>
<source><![CDATA[
int main (int argc, char **argv) {
try {
XMLPlatformUtils::Initialize();
#ifndef XSEC_NO_XALAN
XalanTransformer::initialize();
#endif
XSECPlatformUtils::Initialise();
}
catch (const XMLException &e) {
cerr << "Error during initialisation of Xerces" << endl;
cerr << "Error Message = : "
<< e.getMessage() << endl;
}
// Create a blank Document
DOMImplementation *impl =
DOMImplementationRegistry::getDOMImplementation(MAKE_UNICODE_STRING("Core"));
// Create a letter
DOMDocument *doc = createLetter(impl);
]]></source>
</section>
<section>
<title>Setup for Encryption</title>
<p>
Once the library is initialised, we create a
<em>XENCCipher</em>
object in a manner similar to the creation of a
<em>DSIGSignature</em> object. The <em>XENCCipher</em> 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 <em>XENCCipher</em> object, the sample
uses the <em>RAND_bytes</em> function within the
<strong>OpenSSL</strong>
library to create a random key that will be used during the
encryption process.
</p>
<source><![CDATA[
try {
/* Create the cipher object that we need */
XSECProvider prov;
XENCCipher *cipher;
cipher = prov.newCipher(doc);
/* Now generate a random key that we can use to encrypt the element
*
* First check the status of the random generation in OpenSSL
*/
if (RAND_status() != 1) {
cerr << "OpenSSL random generation not properly initialised" <<
endl;
exit(1);
}
unsigned char keyBuf[24];
if (RAND_bytes(keyBuf, 24) == 0) {
cerr << "Error obtaining 24 bytes of random from OpenSSL" << endl;
exit(1);
}
]]></source>
</section>
<section>
<title>Encryption of Element</title>
<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
<em>cipher</em>
object with a call to <em>setKey(key)</em>.
</p>
<p>
The last line in the following block performs the actual
encryption.
the first parameter to <em>cipher->encryptElement</em> 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 <em>EncryptElement</em> 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>
<source><![CDATA[
/* Wrap this in a Symmetric 3DES key */
OpenSSLCryptoSymmetricKey * key =
new
OpenSSLCryptoSymmetricKey(XSECCryptoSymmetricKey::KEY_3DES_192);
key->setKey(keyBuf, 24);
cipher->setKey(key);
/* Encrypt the element that needs to be hidden */
cipher->encryptElement(g_toEncrypt, ENCRYPT_3DES_CBC);
]]></source>
</section>
<section>
<title>Create an <EncryptedKey></title>
<p>
The following snippet of code uses the previously created
<em>XENCCipher</em> 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 <em>setKEK</em> is used rather than <em>setKey</em>.
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 <em>encryptedKey</em> method returns an
<em>XENCEncryptedKey</em>
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 <em>DOMDocument</em> that was passed in during the
call
to <em>newCipher</em>.)
</p>
<source><![CDATA[
/* Now lets create an EncryptedKey element to hold the generated key
*/
/* First lets load the public key in the certificate */
OpenSSLCryptoX509 * x509 = new OpenSSLCryptoX509();
x509->loadX509Base64Bin(cert, strlen(cert));
/* Now set the Key Encrypting Key (NOTE: Not the normal key) */
cipher->setKEK(x509->clonePublicKey());
/* Now do the encrypt, using RSA with PKCS 1.5 padding */
XENCEncryptedKey * encryptedKey =
cipher->encryptKey(keyBuf, 24, ENCRYPT_RSA_15);
]]></source>
</section>
<section>
<title>Append <EncryptedKey> to
<EncryptedData></title>
<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>
<source><![CDATA[
/*
* Add the encrypted Key to the previously created EncryptedData,
which
* we first retrieve from the cipher object. This will automatically
create
* the appropriate <KeyInfo> element within the EncryptedData
*/
XENCEncryptedData * encryptedData = cipher->getEncryptedData();
encryptedData->appendEncryptedKey(encryptedKey);
]]></source>
</section>
<p>
The above code results in a document that contains the newly
created
<EncryptedData> as follows:
</p>
<source><![CDATA[
<Letter>
<ToAddress>The address of the Recipient</ToAddress>
<FromAddress>The address of the Sender</FromAddress>
<xenc:EncryptedData Type="http://www.w3.org/2001/04/xmlenc#Element";
xmlns:xenc="http://www.w3.org/2001/04/xmlenc#";>
<xenc:EncryptionMethod
Algorithm="http://www.w3.org/2001/04/xmlenc#tripledes-cbc"/>
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#";>
<xenc:EncryptedKey xmlns:xenc="http://www.w3.org/2001/04/xmlenc#";>
<xenc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/>
<xenc:CipherData>
<xenc:CipherValue>Wh8pAkDsQceHiktGxnlhXGfEMPDOLB6FwWp8PLedFEB3L3F6xHUoCOerIvA7Pgvv
VYzVqLv4a5x5YdnCqikkFBLE/fruAUe2Z8ZTEn/CaPYmpzU6qYHALCl7Q61LcbqH
R87TzroBYsYwfHmXmrKHL9K9sB6zmuec1TjVzm2c/Xs=
</xenc:CipherValue>
</xenc:CipherData>
</xenc:EncryptedKey>
</ds:KeyInfo>
<xenc:CipherData>
<xenc:CipherValue>YhqQciiFkLG1z0I1TJC6Pewnzw/gmVuGqcTvHtWpgak/b3NQDRAlv07lJOmBLoHX
23LQ1CdPSxvnyerlJGwkY6xJ0M5tjpDregTVcECXo/bd+x8eIsF2kaawoZGCqD1K
96T36Fx9rHek9bY/Hp1OiQ==
</xenc:CipherValue>
</xenc:CipherData>
</xenc:EncryptedData></Letter>
]]></source>
</section>
<section id="simpledecrypt">
<title>A simple decryption example</title>
<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
<em>simpleDecrypt.cpp</em>.
</p>
<section>
<title>Setup</title>
<p>
The setup process is much the same as for
<jump href="#simpledsa">simpleVerify</jump>. The document
(which is the document created in simpleEncrypt) is parsed
using
Xerces and a <em>DOMDocument</em> is returned.
</p>
</section>
<section>
<title>Load Private Key</title>
<p>
The <em>simpleDecrypt</em> uses a preloaded RSA private key
for
the decryption. A key resolver
(<em>XSECKeyInfoResolver</em>) 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 <em>XSECProvider</em> to obtain a
<em>XENCCipher</em>uses OpenSSL to load the private key from
the
<em>s_privateKey</em> char array.
</p>
<p>
The key is loaded using a call to <em>setKEK</em>. This
method
loads the key as a Key Encryption Key - which means it will
be used
to decrypt an <EncryptedKey> structure.
</p>
<source><![CDATA[
XSECProvider prov;
XENCCipher *cipher;
cipher = prov.newCipher(doc);
/* Load the private key via OpenSSL and then wrap in an OpenSSLCrypto
construct */
BIO * bioMem = BIO_new(BIO_s_mem());
BIO_puts(bioMem, s_privateKey);
EVP_PKEY * pk = PEM_read_bio_PrivateKey(bioMem, NULL, NULL, NULL);
/* NOTE : For simplicity - no error checking here */
OpenSSLCryptoKeyRSA * k = new OpenSSLCryptoKeyRSA(pk);
cipher->setKEK(k);
]]></source>
</section>
<section>
<title>Perform Decryption</title>
<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 <em>findXENCNode</em> library
function is used.
</p>
<p>
The second line, <em>decryptElement</em> actually performs the
decryption. It performs the following steps :
</p>
<ul>
<li>Load the <EncryptedData> structure into an
<em>XENCEncryptedData</em> 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>
<source><![CDATA[
/* Find the EncryptedData node */
DOMNode * encryptedNode = findXENCNode(doc, "EncryptedData");
/* Do the decrypt */
cipher->decryptElement((DOMElement *) encryptedNode);
]]></source>
</section>
<p>
The result of these steps is the decrypted letter.
</p>
<source><![CDATA[
<Letter>
<ToAddress>The address of the Recipient</ToAddress>
<FromAddress>The address of the Sender</FromAddress>
<Text>
To whom it may concern, my secret credit card number is :
0123 4567 89ab cdef
...
</Text></Letter>
]]></source>
</section>
</body>
</document>
