Showing posts with label IT-C#. Show all posts
Showing posts with label IT-C#. Show all posts

Why Coding Standards

Labels: Posted by Kranthi Kiran on Friday, January 7, 2011 at 9:33 AM

Simple: maintainability. If, 6 months down the line, your customer isn't too happy with the product and wants an enhancement in the application you have created, you should be able to do it without introducing new bugs. There are a lot of other good reasons, but this is the one which concerns us more than anything else.


Not following any standard is like going with a temporary solution (which might lead to a permanent problem) and, as you will see, it takes less effort to keep in mind a few simple measures than to do haphazard coding.


All you have to do is study good standards once and keep them in the back of your head. Trust me; it's worth it.


Contents



1. Naming - What is meant by meaningful names
2. Casing - When to use PascalCase and when camelCase
4. Generics - Proper usage
5. Delegates - Proper usage
6. Miscellaneous - Some short tidbits
7. Common Pitfalls - Mistakes we should watch out for
8. References - Where to get more information


Naming



"The beginning of wisdom is to call things by their right names" - Chinese Proverb


"Meaningful" is the keyword in naming. By meaningful names, I mean concise names that accurately describe the variable, method or object. Let's see how this would be in C#:



Namespaces - Names should be meaningful and complete. Indicate your company or name, product and then your utility. Do not abbreviate.



//Good

namespace CompanyName.ProductName.Utility

//Bad

namespace CN.PROD.UTIL


Classes - Class names should always be a noun and, again, should be meaningful. Avoid verbs



//Good

class Image
{
   ...
}
class Filters
{
   ...
}

//Bad

class Act
{
   ...
}
class Enhance
{
   ...
}


Methods - Always use a verb-noun pair, unless the method operates on its containing class, in which case, use just a verb.



//Good

public void InitializePath();
public void GetPath();
public void ShowChanges();
public void System.Windows.Forms.Form.Show();

//Bad

public void Path();
public void Changes();


Methods with return values - The name should reflect the return value.



//Good

public int GetImageWidth(Bitmap image);

//Bad

public int GetDimensions(Bitmap image);


Variables - Do not abbreviate variable names. Variable names should again be descriptive and meaningful.



//Good

int customerCount = 0;
int index = 0;
string temp = "";

//Bad

int cc = 0;
int i = 0;
string t = "";


Private member variables - Prefix class member variables with m_.



public class Image
{
   private int m_initialWidth;
   private string m_filename;
   ...
}


Interfaces - Prefix all interface names with I. Use a name that reflects an interface's capabilities, either a general noun or an "-able".



interface IClock
{
   DateTime Time { get; set; }
   ...
}

interface IAlarmClock : IClock
{
   void Ring();
   DateTime AlarmTime { get; set; }
   ...
}

interface IDisposable
{
   void Dispose();
}

interface IEnumerable
{
   IEnumerator GetEnumerator();
}


Custom attributes - Suffix all attribute class names with Attribute. The C# compiler recognizes this and allows you to omit it when using it.



public class IsTestedAttribute : Attribute
{
   public override string ToString()
   {
      return "Is Tested";
   }
}

//"Attribute" suffix can be omitted

[IsTested]
public void Ring();


Custom exceptions - Suffix all custom exception names with Exception.



public class UserNotExistentException :
    System.ApplicationException
{
   ...
}


Delegates - Suffix all event handlers with Handler; suffix everything else with Delegate.



public delegate void ImageChangedHandler();
public delegate string StringMethodDelegate();


Casing



C# standards dictate that you use a certain pattern of Pascal Casing (first word capitalized) and Camel Casing (all but first word capitalized).


Pascal Casing - use PascalCasing for classes, types, methods and constants.

public class ImageClass
{
   const int MaxImageWidth = 100;
   public void ResizeImage();
}

enum Days
{
   Sunday,
   Monday,
   Tuesday,
   ...
}

Camel Casing - use camelCasing for local variables and method arguments.

int ResizeImage(int imageCount)
{
   for(int index = 0; index < imageCount; index++)
   {
      ...
   }
}


Generics



Generics, introduced in .NET 2.0, are classes that work uniformly on values of different types.



Use capital letters for types; don't use "Type" as a suffix.



//Good

public class Stack ‹T›

//Bad

public class Stack ‹t›
public class Stack ‹Type›


Delegates




Use delegate inference instead of explicit delegate instantiation.



public delegate void ImageChangedDelegate();
public void ChangeImage()
{
   ...
}

//Good

ImageChangedDelegate imageChanged = ChangeImage;

//Bad

ImageChangedDelegate imageChanged =
    new ImageChangedDelegate(ChangeImage);


Use empty parenthesis on anonymous methods without parameters.



public delegate void ImageChangeDelegate();
ImageChangedDelegate imageChanged = delegate()
{
   ...
}


Miscellaneous



  • Avoid putting using statements inside a namespace

  • Check spelling in comments

  • Always start left curly brace { on a new line

  • Group framework namespaces together; add custom and thirdparty namespaces below

  • Use strict indentation (3 or 4 spaces, no tabs)

  • Avoid fully qualified type names

  • Indent comment at the same line as the code

  • All member variables should be declared at the top of classes; properties and methods should be separated by one line each

  • Declare local variables as close as possible to the first time they're used

  • File names should reflect the classes that they contain


Common Pitfalls



Let's face it, we all do these things one time or another. Let's avoid them as best as we can:



Names that make sense to no one but ourselves.



string myVar;
MyFunction();


Single or double letter variable names (this is excusable for local variables).



int a, b, c, a1, j1, i, j, k, ii, jj, kk, etc.


Abstract names.



private void DoThis();
Routine48();
string ZimboVariable;


Acronyms.



//AcronymFunction

AF();
//SuperFastAcronymFunction

SFAT()


Different functions with similar names.



DoThis();
DoThisWillYa();


Names starting with underscores. They look cool, but let's not ;)



int _m1 = 0;
string __m2 = "";
string _TempVariable = "";


Variable names with subtle and context-less meanings.



string asterix = "";
// (this is the best function of all)

void God()
{
   ...
}


Abbreviations.



string num;
int abr;
int i;

0 comments  

Serial Port Communication in C#

Labels: Posted by Kranthi Kiran on Wednesday, December 22, 2010 at 2:14 PM

The serial port is a serial communication interface through which information transfers in or out one bit at a time.
A quick search on Google reveals that there are a lot of free serial port monitor applications available for PC users. However, what these applications lack, is the possibility of controlling the serial port in a direct manner. They are generally good “sniffers” but they do not allow the user to actually write to the serial port or control any device attached to it. The applications with the write capability encapsulated are not for free, and the cheapest costs about 50 Euro – a great deal of money taking into account how easy it is to make a personalized application.
This article will show how it is possible to build such an application using the C# environment. It is not intended to be a C# tutorial, but to teach a user who has basic knowledge of C or C# to integrate serial port control in one of his applications.
For the example application, I have used the SharpDevelop development environment which includes a C# compiler. This is an open source IDE which takes up very little space on your hard drive and can be a good alternative to users who do not want to install the gigabytes of Visual Studio on their PCs for a simple serial port application.
Once you have downloaded and installed the SharpDevelop environment, create a Windows Application project (solution) called SerialPort:

 

Once you have created the application, display the windows form that was automatically created (by clicking on the “Design” button at the bottom of the screen) and unroll the menu available under “Components” available on the left-hand menu:

 
You will notice that one of the components available here is the one called “SerialPort”. Pick that component and drag&drop it over the surface of the form on the right. This will add the component to your project. The object that is created is called “serialPort1” and it will be used to access the serial port. To be able to use this component, however, you need to add at the beginning of your code the directive for using the System.IO.Ports namespace, as this is not added by default when you create the solution: 

using System;
using System.Collections.Generic;
using System.Drawing;
using System.Windows.Forms;
using System.IO.Ports;
Once this is done, create a regular button on the surface of the form, call it “button1” and change its label to “Write”. Then double click on it in order to create the function that will be executed when the button is clicked.

In this function we will perform several tasks. The first one is to configure the baud rate, COM port, number of data bits, parity and stop bits of the communication:
//configuring the serial port
serialPort1.PortName="COM1";
serialPort1.BaudRate=9600;
serialPort1.DataBits=8;
serialPort1.Parity=Parity.None;
serialPort1.StopBits= StopBits.One;
Next, before writing to the port, it needs to be opened:
//opening the serial port
serialPort1.Open();
Please note that if the COM1 port is already used by an application, you will get an error message when this instruction is executed. Alternatively, if you open the COM1 port with your C# application and then fail to close it, any other application trying to use it will not be able to do that.
OK, it is now time to write to the serial port:
//write data to serial port
serialPort1.Write("ABC");
When this instruction is executed, three bytes are sent to the serial port: the ASCII code of “A”, the ASCII code of “B” and the ASCII code of “C”.
Once the write operation is performed, you must not forget to close the port:
//close the port
serialPort1.Close();
So, as a summary, all the code that makes up the body of the function should be:
void Button1Click(object sender, EventArgs e)
{
//configuring the serial port
serialPort1.PortName="COM1";
serialPort1.BaudRate=9600;
serialPort1.DataBits=8;
serialPort1.Parity=Parity.None;
serialPort1.StopBits= StopBits.One;

//opening the serial port
serialPort1.Open();

//write data to serial port
serialPort1.Write("ABC");

//close the port
serialPort1.Close();

}
Now you have a broad path open in front of you, as you will be able to write your own customized applications that can send any data to any device attached to the serial port. The above code is also compatible with USB to Serial converters, provided that their drivers work by emulating COM ports.

0 comments  

Launch Visual Studio from the Command Prompt

Labels: Posted by Kranthi Kiran on Friday, December 17, 2010 at 3:41 PM

If you want to exercise obsessive control about how Visual Studio is launched, you’ll be pleased to know that you can do it all from your friendly neighborhood command prompt.
The Visual Studio IDE executable is called devenv.exe and includes a number of command-line switches that can be very useful. Elsewhere in this book, we have looked at a couple of these switches, but in this hack, you will learn about all the switches and how they can be used.

Typing command-line switches every time you launch an application is time consuming and just plain inefficient. Remember that you can create shortcuts that call an executable using command-line switches; you could have a number of different shortcuts for Visual Studio with different command-line switches.

Setting Fonts

One of the simplest, but very useful, things you can accomplish using command- line switches is setting the font and font size for the IDE. To specify the font, you can use the /fn switch, and to specify the size, you use /fs. It is important to note that this is not the font size of the text or contents of your files, but rather the text size of the IDE. You won’t see it affect the normal menus, but the font and size of the document tabs, options dialog, and so forth will all be in the specified font type and size.
The following command line could be used to set the Visual Studio IDE font to Verdana and the size to 14:
C:\> devenv /fn Verdana /fs 14
This does not need to be set each and every time you run the IDE; these settings will be saved and used from here on out. This is the same setting you can configure under Tools -> Options -> Fonts and Colors, then selecting the Dialogs and Tool Windows option from the Show Settings drop-down.

Execute a Command

Using the command switch, you can launch Visual Studio and automatically call a Visual Studio command. All you need to do is specify the switch /command and then follow it with the name of the command that you want to execute. In this example, I will call the File.OpenSolution command—I almost always open Visual Studio with the intent of opening a solution, so this saves a couple of mouse clicks:
C:\> devenv /command File.OpenSolution
When you run this command, Visual Studio will open, and the New Solution dialog will open. You could also use /command to execute a macro you have written to perform more complex actions.

Run a Solution

You can automatically run a solution from the command line using the /run switch. The following is an example of running a solution from the command line:
C:\> devenv /run HacksWinSample.sln
When this command is run, the IDE will open and automatically jump into debug mode loading your application. You can also use the /runexit switch, which will launch your applications and minimize the IDE. When you close your application, the IDE will be closed as well.

Building Projects and Solutions

You can build your projects or solutions using command-line switches. This can be a great alternative if you don’t have time to configure a build tool like NAnt, but want to create a build process using a batch file. To build a solution, you use the /build switch as well as the /project or /solution switch. Here is an example of building a solution from the command line:
C:\> devenv HacksWinSample.sln /build release
After the /build switch, you specify the solution configuration that you want to use when building this solution—in this example, I have used the release configuration. Running this will build the solution without opening the IDE, and the build results will be returned to the command prompt window. A number of other build switches are detailed in Table 10-1.
Table 10-1. Build switches
Switch Description
/clean Cleans the project or solution according to the configuration of that project or solution
/rebuild Cleans and builds the project or solution
/project Specifies the project to build
/projectconfig Specifies the configuration to use when building the project
/deploy Tells Visual Studio to deploy the solution after it has been built

Other Switches

A number of other command-line switches can be used to do various things with Visual Studio. These command-line switches are shown in Table 10-2. /out Specifies the name of a file to send any build errors to

Table 10-2. Command-line switches
Switch Description
/lcid Specifies the default language to use for the IDE. Example: devenv
/lcid 1033
/mdi Specifies that Visual Studio should be run in MDI mode.
/mditabs Specifies that Visual Studio should be run in MDI mode with tabs on documents enabled.
/migratesettings Tells Visual Studio to trigger the settings migration process, which can be used to move settings from one version of Visual Studio to another. (You usually see this screen the first time you run a new installation of Visual Studio.)
/nologo Launches Visual Studio without the splash screen.
/noVSIP Disables a developer’s VSIP license on this workstation.
/safemode Specifies that Visual Studio should open without loading any VSIP packages.
/setup Resets certain parts of Visual Studio.
/resetskippkgs Enables VSIP packages by clearing any SkipLoading tags. After running safe mode, this will need to be run to reenable any packages you still want to run.
/rootsuffix Can be used to specify a registry suffix.
/? You can always use this switch to view the help for devenv.exe.

0 comments  

Exchange Data More Securely with XML Signatures and Encryption

Labels: Posted by Kranthi Kiran on Monday, December 13, 2010 at 2:24 PM

The XML Signature and XML Encryption standards are being used extensively as building-block technologies. Microsoft® Office InfoPath™ uses XML signatures to sign partial or whole forms. Web services use XML signatures to sign SOAP messages and XML encryption to encrypt them. The XML manifests for ClickOnce®-based applications, new in Visual Studio® 2005, also use XML signatures. The .NET Framework 1.x includes an object model for the XML Signature standard, and the .NET Framework 2.0 adds additional support, while adding an object model for XML encryption as well. This article explains the XML Signature and XML Encryption standards and shows you how to use them with .NET. For the actual XML Signature specification, see the W3C standard at XML-Signature Syntax and Processing.

Digital Signing
Before we dive into the XML Signature standard, let's review the basics of digital signing. Because it's important to prevent a malicious user from altering a message during transmission, digital signing protects the integrity of data and can detect any changes made to it while it's en route to its recipient. Because it's also important to be able to identify a sender, a message is typically signed using the private (secret) key of the sender and verified with the corresponding public key, allowing recipients to confirm the identity of the sender when they know the sender's public key. This prevents a malicious user from pretending to be a known sender, either by trying to send messages as the known sender or by intercepting messages from the known sender and replacing them with their own—a form of the man-in-the-middle attack.
To create a digital signature, first hash the message you are signing using a cryptographic hash function. For any length of input, a cryptographic hash function returns a fixed-length set of bits called the hash value. This hash value cannot be easily converted back to the input. The hash value changes unpredictably when even a single bit changes in the input, so someone cannot find an input that is similar to the original just by finding a similar hash value. One commonly used hash function is SHA-1, which produces a 160-bit hash value.
The next step is to sign the hash value using a signing algorithm and your private key to produce a signature value. You create the signature with your private key so others who have your public key can verify it (more on that later in the article). RSA is a popular cryptographic algorithm to use with signatures.
After you've sent the message and this signature to the recipient, the verification process begins. The received message is hashed with the same hash function used when signing. Then the signature value is verified by passing it, along with the public key and the computed hash, to the signing algorithm. If the computed hash and the signature hash match, then the signature is valid. If the hashes don't match, either the data or the signature has been changed and therefore the integrity of the data is not assured.
You can also sign and verify data using a keyed hash algorithm, but that's beyond the scope of this article. The .NET Framework already includes a rich set of classes for all kinds of hashing, encryption/decryption, and signing/verification algorithms. For more information on these, see the .NET Framework SDK documentation and .NET Framework Security, by Brian LaMacchia, et al (Addison-Wesley, 2002).

XML Signature Basics
You can sign any kind of data using XML Signature, including part of an XML document, other XML documents, or other data of any format. However, in practice, XML signatures are most frequently used to sign other data represented in XML. The XML Signature standard is also very flexible, allowing you to filter and transform your data before you sign it and letting you choose exactly what to sign and how.
Let's take a look at a simple XML Signature scenario: signing an entire document and including the signature in it (see Figure 1). Notice the Signature element that has been added to the document. This element contains the XML signature. Let's look at what each element contains.
 Figure 1 Simple XML Document Before and After Signing

A simple document: 
<docRoot>
  <a>Hello</a>
  <b>World</b>
</docRoot>
 The document when signed: 
<docRoot>
  <a>Hello</a>
  <b>World</b>
  <Signature xmlns="http://www.w3c.org/2000/09/xmldsig#">
    <SignedInfo>
      <CanonicalizationMethod
        Algorithm="http://www.w3c.org/TR/2001/REC-xml-c14n-20010315"/>
      <SignatureMethod
        Algorithm="http://www.w3c.org/2000/09/xmldsig#rsa-sha1"/>
      <Reference URI="">
        <Transforms>
          <Transform
          Algorithm=
          "http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
        </Transforms>
        <DigestMethod
          Algorithm="http://www.w3c.org/2000/09/xmldsig#sha1"/>
        <DigestValue>cbPT0951Ghb2G3UjpVjWw+7q0Bc=</DigestValue>
      </Reference>
    </SignedInfo>
    <SignatureValue>IoEwS(3 lines of Base64 text)XSo=</SignatureValue>
  </Signature>
</docRoot>
SignedInfo The children of this element contain all the information about what is signed and how it was signed. The signature algorithm is actually applied to this element and all of its children to generate the signature.
CanonicalizationMethod This specifies the canonicalization (C14N) algorithm used on the SignedInfo element to normalize the XML. We'll talk more about C14N later in the article.
SignatureMethod This element specifies the signature algorithm for this signature. In this example, the signature algorithm is SHA-1 (for hashing) with RSA (for signing the resulting hash value).
Reference These elements specify the data that will be signed and how it should be processed before hashing. The URI attribute, representing the Uniform Resource Identifier, identifies the data to be signed, while the Transforms element (described later) specifies how to process the data before hashing. In this example, we're using a special URI, the empty string, which specifies that the document containing the signature is the data to be included in the signature.
The XML Signature standard uses an indirect signing mechanism for Reference data. Rather than hashing and then encrypting the hash value for all of the data from the Reference, the standard hashes the data for each Reference, using the algorithm specified by the Reference's DigestMethod element, and then stores the hash value in the DigestValue element of the Reference. Then the SignedInfo element and all of its children (including the Reference elements) are hashed; that hash value is encrypted to generate the signature. So you're really signing the hash of the hash of data referred to in Reference elements, but this scheme still protects the integrity of the data. Figure 2 and Figure 3 show the signing and verification process alongside the matching XML.
Transforms Each Reference element can have zero or more transforms specified for it. These transforms are applied to the data for the Reference in the order they are listed in the XML. Transforms allow you to filter or modify the data for the Reference before the data is hashed. In this example, we're using the enveloped signature transform, which selects all of the XML in the containing document except for the Signature element. We must remove the Signature element from the data to be signed; otherwise we would be modifying the data we're trying to sign when we store the signature value. We'll talk more about transforms later in the article.
SignatureValue This element contains the signature value computed by signing the SignedInfo element and all of its children.
Figure 2 Signing Process 
Now let's discuss the processing model for creating a signature (see Figure 2). First, for each Reference element in the signature:
  • Apply each transform algorithm specified in the Transform elements to the data for the Reference, in the order the transforms appear under the Transforms element.
  • Hash the transformed data using the hashing algorithm specified by the DigestMethod element of the Reference.
  • Store the resulting hash value in the DigestValue element of the Reference.
The next step is to canonicalize the SignedInfo element and its children using the algorithm specified in the CanonicalizationMethod element of the signature. Then you sign the SignedInfo element and its children using the algorithm specified in the SignatureMethod element of the signature. The signature value is stored in the eponymous SignatureValue element.
Figure 3 Verification Process 
Signature verification is the inverse of the process just described (see Figure 3). First, you must canonicalize the SignedInfo element and its children using the C14N algorithm specified in the CanonicalizationMethod element. Then you must verify the signature value stored in the SignatureValue element against the SignedInfo element and its children.
Finally, for each reference element in the signature:
  • Apply each transform algorithm specified in the Transform elements of the Reference to the data for the Reference, in the order the transforms appear under the Transforms element.
  • Hash the transformed data for the reference using the hashing algorithm that is specified by the DigestMethod element of the reference.
  • Compare the hash value computed with the value stored in the DigestValue element.
If the signature verification succeeds and the hash value for each reference is equal to the one stored in the signature, the XML signature is valid. Otherwise, either the data referred to by one of the reference elements has changed, or the signature element has been changed.
A signature embedded in the document it signs is called an enveloped signature. The code to create this kind of signature is shown in Figure 4. The code to verify the signature is shown in Figure 5.
 Figure 5 Verifying an Enveloped Signature 
using System.Security.Cryptography;
using System.Security.Cryptography.Xml;
// Also, add a reference to System.Security.dll

// Load the signed data
XmlDocument doc = new XmlDocument();
doc.PreserveWhitespace = true;
doc.Load("data-signed.xml");

// Find the Signature element in the document
XmlNamespaceManager nsm = new XmlNamespaceManager(new NameTable());
nsm.AddNamespace("dsig", SignedXml.XmlDsigNamespaceUrl);
XmlElement sigElt = (XmlElement)doc.SelectSingleNode(
  "//dsig:Signature", nsm);

// Load the signature for verification
SignedXml sig = new SignedXml(doc);
sig.LoadXml(sigElt);

// Verify the signature, assume the public key part of the
// signing key is in the key variable
if (sig.CheckSignature(key))
    Console.WriteLine("Signature verified");
else 
    Console.WriteLine("Signature not valid");
 Figure 4 Creating an Enveloped Signature 
using System.Security.Cryptography;
using System.Security.Cryptography.Xml;
// Also, add a reference to System.Security.dll

// Assume the data to sign is in the data.xml file, load it, and
// set up the signature object.
XmlDocument doc = new XmlDocument();
doc.Load("data.xml");
SignedXml sig = new SignedXml(doc);

// Make a random RSA key, and set it on the signature for signing.
RSA key = new RSACryptoServiceProvider();
sig.SigningKey = key;

// Create a Reference to the containing document, add the enveloped
// transform, and then add the Reference to the signature
Reference refr = new Reference("");
refr.AddTransform(new XmlDsigEnvelopedSignatureTransform());
sig.AddReference(refr);

// Compute the signature, add it to the XML document, and save
sig.ComputeSignature();
doc.DocumentElement.AppendChild(sig.GetXml());
doc.Save("data-signed.xml");
You've seen how to create and verify enveloped signatures. While they are commonly used and handy for signing entire XML documents, the XML Signatures standard lets you sign other data as well by specifying different URIs in the Reference element. So let's take a look at different types of references next.

References
In addition to enveloped references (a Reference element that has an empty string for the URI attribute), there are two other broad types of references defined in the XML Signature standard: references to detached data and references to XML data by ID. Detached data is outside of the XML document containing the signature. These references can point to another XML document or to any other type of resource. You would typically use this type of reference when signing multiple resources in one signature, such as an XML document and some other files that are referred to by the document. The following XML code fragment shows an example of a detached reference: 
<Reference URI="http://www.example.com/foo.jpg">
  <DigestMethod
    Algorithm="http://www.w3c.org/2000/09/xmldsig#sha1" />
  <DigestValue>cbPT0951Ghb2G3UjpVjWw+7q0Bc=</DigestValue>
</Reference>
In order to create a detached reference using the Framework classes, you simply set the URI of the reference to the URI of the resource when creating the reference object, and then add the reference to the signature, as shown here: 
// Create a Reference to detached data, assume a SignedXml object in sig
Reference refr = new Reference("http://www.example.com/foo.jpg");
sig.AddReference(refr);
References to XML data by ID point to XML within the document containing the signature or within the signature itself. For these references, the signature engine looks for an element with an Id attribute that matches the URI in the reference, not including the #. Here's an example of an ID-based reference: 
<Reference URI="#myData">
  <DigestMethod
    Algorithm="http://www.w3c.org/2000/09/xmldsig#sha1" />
  <DigestValue>cbPT0951Ghb2G3UjpVjWw+7q0Bc=</DigestValue>
</Reference>
If the element with the Id of "myData" is in the document containing the signature, this reference is complete and the signature engine will find it when processing the signature. You would typically use this type of reference to limit the scope of a signature to a specific part of an example document. For example, in a document processing application, a reviewer would only sign the portions of the XML document she reviewed, not the entire document.
The standard also allows you to add arbitrary data to the signature in an Object element. The XML for an Object element looks like the following line of code: 
<Object Id="myData">Your XML goes here</Object>
 To create an ID-based reference to an element that is already in the document containing the signature, add code like this: 
// Create a Reference to XML data in the containing document,
// assume a SignedXml object in sig
Reference refr = new Reference("#myData");
sig.AddReference(refr);
If the ID-based reference is to an Object element in the signature, you must also add a DataObject to the signature in addition to adding the reference, as in the code that was just shown. The data object can contain any XML that you pass in. 
// Adds a DataObject with an Id of "#myData" to the signature, assume a 
// SignedXml object in sig, and xml data of type XmlNodeList in data
DataObject dobj = new DataObject();
dobj.Id = "myData";  // Note: no #
dobj.Data = data;    // XML Data of the Object
sig.AddObject(dobj);
 You would typically use a reference to an Object element for signing metadata about the signature, such as a unique identifier for the signer or some other information about the signature.

Transforms
Transforms give you even more control over the content signed by allowing you to modify the data for a reference before the hash value for that data is generated. The enveloped signature transform, for example, removes the Signature node from the XML document before signing it. A reference can specify any number of transforms, which are applied in the order specified in the Transforms element. The .NET Framework classes support the following transforms in addition to the enveloped signature transform that we mentioned earlier:
  • Any canonicalization algorithm can be used as a transform.
  • The Base64 transform allows you to decode data in the Base64 encoding.
  • The XSLT transform allows you to apply an XSLT stylesheet to XML data before signing it. The XSLT stylesheet to be applied is specified as XML under the Transform element.
  • The XPath transform allows you to filter XML data with an XPath expression.
The XPath expression is specified as the text content of an XPath element under the Transform element. It's important to note that the XPath transform acts as a filter, not as a means of selecting nodes in the XML being passed as input. The transform evaluates the XPath expression against each node passed as input to the transform, and the result is converted to a Boolean. An input node is considered to pass the evaluation and will be included in the output of the transform if the result of the evaluation is true. Consider the following XML input to the transform: 
<a>
  <b>Some data</b>
  <c>More data</c>
</a>
<d>
  <b>Even more data</b>
</d>
 Let's say we only want to select "b" nodes for signing. An XPath transform with the XPath expression of "ancestor-or-self::b" will return the following nodeset, which is what we want: 
<b>Some data</b>
<b>Even more data</b>
 The Transform element for this XPath expression would look like the following code snippet: 
<Transform
  Algorithm="http://www.w3c.org/TR/1999/REC-xpath-19991116">
  <XPath>ancestor-or-self::b</XPath>
</Transform>
To create transforms programmatically when signing, create an instance of a transform object, set its properties appropriately, and add it to the reference to which it applies. The following example adds the XPath transform used in the previous example to a reference to create a transform: 
// Add an XPath transform to a reference.
// Assume a Reference object in refr 
XmlDocument doc = new XmlDocument();
doc.LoadXml("<XPath>ancestor-or-self::b</XPath>");
XmlDsigXPathTransform xptrans = new XmlDsigXPathTransform();
xptrans.LoadInnerXml(doc.ChildNodes);
refr.AddTransform(xptrans);

Canonicalization
The purpose of canonicalization is to produce the same XML data for two XML fragments that are logically the same, but may not be represented by the same text. For example, take a look at the following two code fragments. They are logically the same; they differ only in text representation. But if you were to hash both of them as is, the hash values would be different: 
<root>
  <a   >Some text</a>
  <b attr1="yes" attr2="no"></b>
  <c    Id="foo">More text</c>
</root>

<root>
  <a>Some text</a>
  <b attr2="no" attr1="yes" />
  <c Id="foo">More text</c>
</root>
 To avoid this problem, the default canonicalization algorithm specified in the standard performs a number of tasks including the removal of white space in start and end tags and the conversion of empty elements to start/end tag pairs. It does not, however, change any white space in the content of elements. The complete list of operations performed is available in the Canonical XML recommendation, located at Canonical XML.
The signature engine automatically canonicalizes data when necessary to comply with the W3C standard. Specifically, the signature engine canonicalizes XML data anytime it needs to convert it to binary data for hashing. This happens when it prepares to sign the SignedInfo element and its children, for instance. It also may happen when preparing a reference or the output of a transform for signing. For example, if you use an ID-based reference to other XML data in the document containing the signature, and the reference has no transforms associated with it, the signature engine will canonicalize the XML data for that reference before hashing the data.

Key Management
The XML Signature standard provides the KeyInfo element to help with key management. This element can store a key name, key value, key retrieval method, or certificate information to help receivers verify the signature. The standard does not specify how or if any information in the KeyInfo element should be trusted.
The KeyInfo element can be useful when the sender and recipient share a list of trusted keys or if you come up with some other method for mapping key names to keys, for example. The .NET Framework 1.x has some support for key name, value, and retrieval method. The .NET Framework 2.0 also includes support for X.509 certificates.
Let's say the sender and recipient share a list of keys. The recipient has a public key for each sender from whom she expects to receive messages. The signing application can add the following code to add a KeyInfo element to the signature: 
// Adds an KeyInfo element with RSA public key information to the 
// signature. 
// Assumes a SignedXml object in sig, and an RSA object in key.
KeyInfo ki = new KeyInfo();
ki.AddClause(new RSAKeyValue(key));
sig.KeyInfo = ki;
 This code should be added before ComputeSignature is called. It will produce a KeyInfo element in the signature that looks something like the following code: 
<KeyInfo><KeyValue><RSAKeyValue>
  <Modulus>4LfG(2 lines of Base64 text)2Fr=</Modulus>
  <Exponent>AQAB</Exponent>
</RSAKeyValue></KeyValue></KeyInfo>
 This represents the RSA public key used to sign the XML document. The receiving application should compare this key to a list of trusted keys and should not trust the document if the public key is not on the list. Otherwise an attacker could replace a signed document while in transit, signing it with another key. If a signature includes an RSAKeyValue like this, the verification code can call the CheckSignature method of the SignedXml class that takes no parameters, and the .NET Framework will figure out the key from the RSAKeyValue element. Here's an example: 
// Verify a signature that includes RSAKeyInfo or DSAKeyInfo.
// Assume a SignedXml object in sig.
bool verified = sig.CheckSignature();

Signature Profiles
Along with the flexibility of XML signatures comes some amount of risk. In particular, because transforms are so flexible, it can be difficult to figure out exactly what data was covered by the signature, which can lead to unexpected or insecure results. These signature profiles can help in this regard by specifying the form of signature your application supports. While there is no standard for signature profiles a signature profile should at the least specify references and transforms that the application expects for a signature, so you can be sure that the data you expect to be signed is indeed signed. Signature profiles could also contain additional data, such as signing algorithms or key sizes expected for signed data. Your application should check and enforce that those signatures it creates and verifies comply with the signature profile that your application supports.
To better understand why profiles are important, consider Figure 1. Suppose you are writing an application that accepts XML signed data, but your application only expects signatures that use the enveloped signature transform and no other transforms. Now someone sends you a signed document with an extra XPath transform, as shown in Figure 6.
 Figure 6 Signed Document with an Extra Transform 
<docRoot>
  <a>Hello</a>
  <b>World</b>
  <Signature xmlns="http://www.w3c.org/2000/09/xmldsig#">
    <SignedInfo>
      <CanonicalizationMethod
        Algorithm="http://www.w3c.org/TR/2001/REC-xml-c14n-20010315"/>
      <SignatureMethod
        Algorithm="http://www.w3c.org/2000/09/xmldsig#rsa-sha1"/>
      <Reference URI="">
        <Transforms>
          <Transform
            Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-
              signature"/>
          <Transform
            Algorithm="http://www.w3c.org/TR/1999/REC-xpath-19991116">
              <XPath>ancestor-or-self::a</XPath>
         </Transform>
       </Transforms>
       <DigestMethod
         Algorithm="http://www.w3c.org/2000/09/xmldsig#sha1"/>
       <DigestValue>mN4R0653F4ethOiTBeAu+7q0Be=</DigestValue>
     </Reference>
    </SignedInfo>
    <SignatureValue>X4Ie(3 lines of Base64 text)nP3=</SignatureValue>
  </Signature>
</docRoot>
In the example in Figure 6, the signature only covers the "a" element in the sample document. If you just loaded the document and called the CheckSignature method of the SignedXml class, the signature may still verify even though the "b" element is not covered by the signature, because the signature engine will apply the transform specified in the signature. If your application relies on the "b" element being covered in the signature, the integrity of your data has been compromised. The application should verify the signature profile it expects by checking that there is just one reference that has an empty string as the URI and that the reference has one transform: the enveloped signature. It would reject any other signature profile when verifying a signature. Some sample code that checks this signature profile is shown in Figure 7.
 Figure 7 Checking a Signature Profile 
// This method checks the signature profile for the signature
// in the supplied document. It ensures there is only one
// Signature element and only one enveloped reference with only
// one enveloped signature transform
public bool CheckSignatureProfile(XmlDocument doc)
{
    // Make sure there is only one Signature element
    XmlNamespaceManager nsm = new XmlNamespaceManager(new NameTable());
    nsm.AddNamespace("dsig", SignedXml.XmlDsigNamespaceUrl);
    XmlNodeList sigList = doc.SelectNodes("//dsig:Signature", nsm);
    if (sigList.Count > 1)
        return false; //Wrong number of Signature elements

    //Make sure the Signature element has only one Reference
    XmlElement sigElt = (XmlElement)sigList[0];
    XmlNodeList refList = sigElt.SelectNodes(
        "dsig:SignedInfo/dsig:Reference", nsm);
    if (refList.Count > 1)
        return false; //Wrong number of Reference elements

    // Make sure the Reference URI is ""
    XmlElement refElt = (XmlElement)refList[0];
    XmlAttributeCollection refAttrs = refElt.Attributes;
    XmlNode uriAttr = refAttrs.GetNamedItem("URI");
    if ((uriAttr == null) || (uriAttr.Value != ""))
        return false; // Wrong type of reference

    // Make sure the only tranform is the enveloped signature transform
    XmlNodeList transList = refElt.SelectNodes(
        "dsig:Transforms/dsig:Transform", nsm);
    if (transList.Count != 1)
        return false; //Wrong number of Transform elements
    XmlElement transElt = (XmlElement)transList[0];
        string transAlg = transElt.GetAttribute("Algorithm");
    if (transAlg != SignedXml.XmlDsigEnvelopedSignatureTransformUrl)
        return false; //Wrong type of transform

    return true;
}
So far, we've looked at some different aspects of the XML Signature standard and the support for it in the .NET Framework. Let's put some of these features together into a more complete example. Suppose you're writing an application to exchange messages in XML and you want to sign the entire content of the message. You also want to add some XML data about the signer to the signature element as an object, only signing the signerID element of this data. Your application has access to a well-known list of keys, so you will also store the public key information in the signature and check to make sure the key maps to a well-known key during verification. The code for signing and verifying a message is included in the complete code download for this article. Signing a message with this code will produce an XML signature that looks something like Figure 8.
 Figure 8 A More Complex Signed Document 
<root>
  <myData1>Some Data</myData1>
  <myData2>More data</myData2>
  <Signature xmlns="http://www.w3c.org/2000/09/xmldsig#">
    <SignedInfo>
      <CanonicalizationMethod
        Algorithm="http://www.w3c.org/TR/2001/REC-xml-c14n-20010315"/>
      <SignatureMethod
        Algorithm="http://www.w3c.org/2000/09/xmldsig#rsa-sha1"/>
      <Reference URI="">
        <Transforms>
          <Transform
           Algorithm=
           "http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
        </Transforms>
        <DigestMethod
          Algorithm="http://www.w3c.org/2000/09/xmldsig#sha1"/>
        <DigestValue>cbPT0951Ghb2G3UjpVjWw+7q0Bc=</DigestValue>
      </Reference>
      <Reference URI="#signer">
        <Transforms>
          <Transform
          Algorithm=
          "http://www.w3c.org/TR/1999/REC-xpath-19991116">
            <XPath xmlns:my="http://example">
              ancestor-or-self::my:SignerID
            </XPath>
          </Transform>
        </Transforms>
        <DigestMethod
          Algorithm="http://www.w3c.org/2000/09/xmldsig#sha1"/>
        <DigestValue>mN4R0653F4ethOiTBeAu+7q0Be</DigestValue>
      </Reference>
    </SignedInfo>
    <SignatureValue>IoEwS...</SignatureValue>
    <KeyInfo>
      <KeyValue>
        <RSAKeyValue>
          <Modulus>4LfG(2 lines of Base64 text)2Fr=</Modulus>
          <Exponent>AQAB</Exponent>
        </RSAKeyValue>
      </KeyValue>
    </KeyInfo>
    <Object Id="signer">
      <my:SignerData xmlns:my="http://example">
        <my:SignerName>Mike</my:SignerName>
        <my:SignerID>4815</my:SignerID>
      </my:SignerData>
    </Object>
  </Signature>
</root>

New Features in the .NET Framework 2.0
All the XML Signature features discussed so far are available in both the .NET Framework 1.x and 2.0. XML Encryption and X.509 certificate integration are new to version 2.0. X.509 certificate integration makes it easier to use X.509 certificates with XML Signature. The new X509CertificateEx class and related classes make it easier to manipulate and use certificates, and the XML signing object model uses these classes when appropriate. We'll talk more about X.509 integration at the end of this article.
XML Encryption is another W3C standard. Just as XML Signature specifies a format and processing model for creating digital signatures in XML, XML Encryption standardizes how to encrypt data in XML. XML digital signatures are driven through the SignedXml class, and XML encryption is performed using the new EncryptedXml class.
Although XML encryption can be used to encrypt arbitrary data, you would most frequently use it to encrypt other XML. When used in this way, you have a lot of flexibility in how documents are encrypted. For instance, different nodes of an XML document could be encrypted with different keys, while some nodes are left in plain text. And since encrypting something with the EncryptedXml class results in XML, you can even encrypt the encrypted results, a process known as super encryption.
Let's take a look at some encrypted XML (see Figure 9). One interesting thing to note right away is that the XML Encryption standard uses the XML Signature namespace for some elements, including the KeyInfo element.
 Figure 9 XML Document Before and After Encryption

A simple document: 
<docRoot>
  <a>Hello</a>
  <b>World</b>
</docRoot>
 The document when encrypted: 
<docRoot>
  <EncryptedData Type="http://www.w3.org/2001/04/xmlenc#Element"
  xmlns="http://www.w3.org/2001/04/xmlenc#">
    <EncryptionMethod
    Algorithm="http://www.w3.org/2001/04/xmlenc#aes256-cbc"/> 
    <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
      <EncryptedKey xmlns="http://www.w3.org/2001/04/xmlenc#">
        <EncryptionMethod
        Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/> 
        <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
          <KeyName>recipient_public_key</KeyName> 
        </KeyInfo>
        <CipherData>
          <CipherValue>PrI6(3 lines of Base64 text)Dwy4=</CipherValue> 
        </CipherData>
      </EncryptedKey>
    </KeyInfo>
    <CipherData>
      <CipherValue>awcH(3 lines of Base64 text)NNqQ=</CipherValue> 
    </CipherData>
  </EncryptedData>
</docRoot>

EncryptedData Elements
EncryptedData is the root element generated by encrypting the XML, and it contains all the information about the data. EncryptedData contains three main subelements: EncryptionMethod specifies which algorithm was used to encrypt the data, KeyInfo element provides information about which key to use to decrypt the data, and the CipherData or CipherReference element contains the actual encrypted information. The EncryptionMethod element specifies the algorithm used to encrypt and decrypt the cipher data. The algorithms are specified by a URI, like the XML Signature standard. EncryptionMethod is used for both encrypted data and encrypted keys, but not every algorithm can be used in both places. Figure 10 shows where each algorithm can be used. Note that Advanced Encryption Standard (AES) is also available with 192- and 128-bit keys; you just change the key size in the URI.
 Figure 10 Where to Use Encrypting Algorithms

  URI Properties of EncryptedXml Class Encrypting Data Encrypting Keys
AES XmlEncAES256Url  
XmlEncAES256KeyWrapUrl  
DES XmlEncDESUrl  
TripleDES XmlEncTripleDESUrl  
XmlEncTripleDESKeyWrapUrl  
RSA XmlEncRSA1_5Url  
Before any data can be encrypted or decrypted, the encryption engine needs to know which key should be used for encryption and decryption. Keys can be identified in two ways, the easiest of which is to assign the key a name and place a KeyName element within the KeyInfo element. The application decrypting the document will be responsible for taking the KeyName tag and providing the key that matches the name given.
Instead of providing only the key's name, a key can also be embedded directly into the KeyInfo element as an EncryptedKey. EncryptedKey contains the same elements as EncryptedData: the encryption method, the key used to decrypt this key, and the cipher data that makes up the encrypted key.
Encrypted keys are often used in combination with named keys as random session keys. First a random session key is generated and used to encrypt the XML. Then the session key is itself encrypted with a named key that is known by anyone who needs to decrypt the document. Finally, the named key would be inserted into the key info element of the encrypted session key, and the encrypted session key attached to the encrypted data. The sample in Figure 9 shows this. The encryption method for the XML data is 256-bit AES, and the key for the AES algorithm has been encrypted. The EncryptedKey element contains information about how the key for the AES algorithm was encrypted. In this sample, it was encrypted using an RSA key named recipients_public_key. The applications using XML Encryption would have to map this name to an actual key.
The actual encrypted data may either be embedded into the EncryptedData element or placed in a separate location and then referenced from EncryptedData. If the cipher data is to be placed directly into EncryptedData, it is placed in a CipherData element as Base64-encoded binary. The example shown in Figure 9 uses a CipherData element.
Another scenario involves placing the encrypted data outside the EncryptedData element. The cipher text might be placed anywhere from another element in the document to a remote Web site. In both cases, a CipherReference is used instead of a CipherData element (see Figure 11).
 Figure 11 CipherReferences

CipherReference Location URI Format Cipher Text Format
Same document #order Base64 string
Remote Web site http://www.example.com/order.bin Binary
CipherReferences to remote Web sites present an interesting security scenario. In the process of decrypting the XML, the decryption engine will have to go to an arbitrary Web site and download the cipher text. Since the document being decrypted may not be trusted as much as the code that's doing the decryption, this operation should be done in a sandbox. This is accomplished by providing evidence to the EncryptedXml object that it will use when resolving any CipherReferences.
Sandboxing allows for safer code execution since the decrypting application may not have the same permissions as the site that supplies the encrypted data. For instance, if an application attempts to decrypt an untrusted site, and the untrusted site does not have access to some trusted data on a secure, trusted site, it could cause the decrypting application to access that file for it by including a cipher reference.
Since the .NET security policy revolves around evidence, generally the evidence supplied should include at least Site, Zone, and Url objects, as shown here: 
// Create evidence based on the referring document
Evidence evidence = new Evidence();
evidence.AddHost(new Zone(SecurityZone.Internet));
evidence.AddHost(new Site("untrustedsite"));
evidence.AddHost(new Url("untrustedsite/encrypted.xml"));

EncryptedXml exml = new EncryptedXml(untrustedDoc, evidence);

XML Encryption Example
Now let's look at how to use the classes in .NET Framework 2.0. This example shows a Web site that sells CDs. Each purchase is filed as an XML document that contains details on what was ordered, shipping information, and a credit card number. Figure 12 shows some sample XML for an order.
 Figure 12 XML of a CD Order 
<order>
   <purchase>
     <item quantity="1">Def Leppard: Pyromania</item>
     <item quantity="1">Ozzy Osbourne: Goodbye to Romance</item>
   </purchase>
   <shipping>
     <to>Shawn Farkas</to>
     <street>One Microsoft Way</street>
     <zip>98052</zip>
   </shipping>
   <payment>
     <card type="visa">0000-0000-0000-0000</card>
   </payment>
</order>
In this instance, it is acceptable for anyone inside the company to see the items in the order, but you might want to secure some of the more sensitive data such as the shipping address and credit card information. In fact, you might even want to encrypt them separately, so that only the billing department has access to the credit card information, and only the shipping department has access to the shipping address.
To accomplish this, the portion of the XML under the payment element would be encrypted so that only the billing department has access to it. A separate key that is only available to the shipping department would be used to encrypt the shipping element. Finally, the entire order would be encrypted with a key available to anyone in the company.
The first step is to create an EncryptedXml object. This is done by passing in the document that has the data to be encrypted or decrypted, as shown here: 
// Assumes the order is in the order.xml file.
XmlDocument doc = new XmlDocument();
doc.Load("order.xml");
EncryptedXml exml = new EncryptedXml(doc);
Before the XML can be encrypted, the keys to be used have to be mapped to their corresponding names. These are the names that will appear in KeyName elements. You use the AddKeyMapping method of the EncryptedXml for this: 
// Set up the key mapping. Assumes a method called GetBillingKey
// that returns the RSA key for the billing department.
RSA billingKey = GetBillingKey();
exml.AddKeyNameMapping("billing", billingKey);
Once the key-to-name mapping is set up, encrypting the XML is easy. The first step is to call the Encrypt method, which does the actual encryption and returns an EncryptedData object representing the encrypted portion of the document. After that, you call a utility method to swap the unencrypted portion of the original XML document for the new encrypted data: 
// Find the element to encrypt.
XmlElement paymentElement = 
  doc.SelectSingleNode("//order/payment") as XmlElement;
// Encrypt the payment element, passing in the key name.
EncryptedData encryptedPayment = 
  exml.Encrypt(paymentElement, "billing");
// Swap the encrypted element for the unencrypted element.
EncryptedXml.ReplaceElement(paymentElement, encryptedPayment, true);
 This will result in the encrypted XML shown in Figure 13.
 Figure 13 CD Order with Payment Information Encrypted 
<order>
  <purchase>
    <item quantity="1">Def Leppard: Pyromania</item> 
    <item quantity="1">Ozzy Osbourne: Goodbye to Romance</item> 
  </purchase>
  <shipping>
    <to>Shawn Farkas</to> 
    <street>One Microsoft Way</street> 
    <zip>98052</zip> 
  </shipping>
    <payment>
      <EncryptedData Type="http://www.w3.org/2001/04/xmlenc#Element" 
           xmlns="http://www.w3.org/2001/04/xmlenc#">
        <EncryptionMethod Algorithm="http://www.w3.org/2001/04/
             xmlenc#aes256-cbc" />
        <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
          <EncryptedKey xmlns="http://www.w3.org/2001/04/xmlenc#">
            <EncryptionMethod Algorithm="http://www.w3.org/2001/04/
                 xmlenc#kw-aes256" />
            <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
              <KeyName>billing</KeyName>
            </KeyInfo>
            <CipherData>
              <CipherValue>Sce6lLD+u2f8HzPFyuGxTF32z4mb2ugql3JuJIPAqIP98iYs+Muhqg==
              </CipherValue>
            </CipherData>
          </EncryptedKey>
        </KeyInfo>
        <CipherData>
          <CipherValue>FXKC(3 lines of Base64 text)ApqQt</CipherValue>
        </CipherData>
      </EncryptedData>
    </payment>
</order>
Looking at the encrypted data, you can see the various parts that we've described. First, the EncryptionMethod element shows the URI for AES-256, meaning that the document was encrypted with the AES algorithm (as implemented by the RijndaelManaged class) with a 256-bit key.
The Encrypt method generates a random session key for you; this key is encrypted in the KeyInfo element. From looking at the EncryptedKey element you can see that it was encrypted with the RSA algorithm by a key named "billing." The CipherData element holds the encrypted value of the key. Following the KeyInfo is the CipherData that contains the encrypted contents of what used to be the payment element.
Decrypting the document just shown is easy, thanks to the DecryptDocument method of EncryptedXml. First, you load the document with encrypted content: 
// Assumes the encrypted order is in encrypted.xml
XmlDocument doc = new XmlDocument("encrypted.xml");
EncryptedXml exml = new EncryptedXml(doc, documentEvidence);
 Next, you set up the key name mappings, like this: 
// Set up the key mapping. Assumes a method called GetBillingKey
// that returns the RSA key for the billing department.
RSA billingKey = GetBillingKey();
exml.AddKeyNameMapping("billing", billingKey);
 Finally, you call DecryptDocument. This method will take care of decrypting the cipher text and replacing the encrypted XML with its decrypted contents. 
// Decrypt the encrypted XML in the document
exml.DecryptDocument();
Behind the scenes, the encryption engine will look for any EncryptedData elements when DecryptDocument is called. In this case, it finds only the one below the payment element. Once it finds this element, it will look at the KeyInfo clause and see that it holds an encrypted 256-bit AES key. The KeyInfo for the encrypted key will show that it was encrypted with an RSA key named billing. It then checks the key mapping table for a key named billing. We added a key mapping for a key named billing, so the engine then decrypts the encrypted key. Now that it has the key, the engine decrypts the CipherData. The results of the decrypted CipherData are then swapped for the EncryptedData element. The engine will follow this process for each EncryptedData element it finds in the document when DecryptDocument is called.

X.509 Support
One of the challenges in security is trust. Securely distributing and storing trusted public keys on a network is not easy. Windows® provides lots of infrastructure for solving this problem, however. The Cryptographic API (CAPI) provides support for distributing, manipulating, and storing X.509 certificates. The support that CAPI provides is also known as Public Key Infrastructure (PKI).
An X.509 certificate provides additional information about a key. Certificates specify who issued the key, to whom the key was issued, and when the certificate is valid, along with the actual key information. Certificates are issued by Certificate Authorities (CAs). A CA is an entity (an external company or your company's IT department, for example) that you trust to vouch for the identity of a certificate holder. If you have a valid certificate containing your billing department's public key that is issued by a CA you trust, you can be sure the public key is really the billing department's.
The Windows PKI support allows you to securely store certificates in a certificate store on a computer, add and remove certificates in certificate stores on machines across the network, add and remove trusted CAs on machines across the network, and obtain and verify information about individual certificates, among other things. This allows you, for example, to distribute the certificate containing the public key for your company's billing department to all the computers on your company's network. In the .NET Framework 1.x, you had to call unmanaged APIs to take advantage of most of this support. In the .NET Framework 2.0, most of these APIs are available in managed code, via the X509CertificateEx class and related classes. The XML Signature classes support the X509CertificateEx class directly.
To create an XML signature with a certificate, you simply get the private key from the certificate's PrivateKey property and use it for the SignedXml object's signing key. 
// Use the private key from the certificate. Assumes a SignedXml
// object in sig and an X509CertificateEx object in cert.
sig.SigningKey = cert.PrivateKey;
 Of course, the certificate must have a private key associated with it, or the PrivateKey property returns null.
You can also add the X.509 certificate information to the KeyInfo element of the signature by using the KeyInfoX509Data class, as shown in the following code: 
// Add X.509 certificate info to the KeyInfo element. Assumes a
// SignedXml object in sig and an X509CertificateEx in cert.
KeyInfoX509Data keyInfoX509 = 
  new KeyInfoX509Data(cert, X509IncludeOption.EndCertOnly);
sig.KeyInfo.AddClause(keyInfoX509);
To verify an XML signature signed with a certificate's private key, you can call a new overload of the CheckSignature method of the SignedXml class. This new overload takes an X509CertificateEx object and a Boolean. If the Boolean is set to true, the method will verify the signature against the public key in the certificate and verify the certificate by checking key usage and building a chain to a trusted root issuer. 
// Check the signature against the cert and verify the cert. Assumes a
// SignedXml object in sig and an X509CertificateEx object in cert.
bool verified = sig.CheckSignature(cert, true);
You can also use the CheckSignature method that takes no parameters to verify a signature, but it will not also verify an X.509 certificate if one was used to sign the XML. You would have to recreate the X509CertificateEx object from the KeyInfo and verify it as a separate step.
For more information about creating X.509 certificates for testing purposes, see the Certificate Creation Tool (Makecert.exe) topic in the .NET Framework SDK documentation.
The .NET Framework 2.0 adds a few new transforms and canonicalization algorithms to the signature engine. These include the Exclusive C14N canonicalization algorithm, XML Decryption transform, and the LTA transform. Figure 14 contains a complete table of the transforms and canonicalization algorithms available in the .NET Framework 2.0 signature engine.
 Figure 14 Transforms and Canonicalization Algorithms

Class Description
XmlDecryptionTransform Decrypts encrypted XML
XmlDsigBase64Transform Decodes base64 encoded data
XmlDsigC14NTransform Performs C14N canonicalization (see http://www.w3.org/TR/xml-c14n for more information)
XmlDsigEnvelopedSignatureTransform Removes an enveloped signature from a document
XmlDsigExcC14NTransform Performs exclusive C14N canonicalization (see http://www.w3.org/TR/2002/REC-xml-exc-c14n-20020718 for more information)
XmlDsigXPathTransform Applies an XPath filter to the input XML
XmlDsigXsltTransform Applies an XSLT transform to the input XML
XmlLicenseTransform Implements the LTA transform
XmlDsigC14NWithCommentsTransform Performs C14N canonicalization, but leaves comments in the canonicalized XML
XmlDsigExcC14NWithCommentsTransform Performs exclusive C14N canonicalization, but leaves comments in the canonicalized XML

Conclusion
We've discussed the basics of the XML Signature standard and how it is implemented in the .NET Framework 1.x. We've also covered some new features in the .NET Framework 2.0, including support for the XML Encryption standard and X.509 certificate integration for XML signing. These building-block technologies allow you to interoperate with other applications using the standards and build standards support into your own applications.

1 comments  

Subscribe to: Posts (Atom)