Reference Class

 

Represents the <reference> element of an XML signature.

Namespace:   System.Security.Cryptography.Xml
Assembly:  System.Security (in System.Security.dll)

System::Object
  System.Security.Cryptography.Xml::Reference

[HostProtectionAttribute(SecurityAction::LinkDemand, MayLeakOnAbort = true)]
public ref class Reference 

NameDescription
System_CAPS_pubmethodReference()

Initializes a new instance of the Reference class with default properties.

System_CAPS_pubmethodReference(Stream^)

Initializes a new instance of the Reference class with a hash value of the specified Stream.

System_CAPS_pubmethodReference(String^)

Initializes a new instance of the Reference class with the specified Uri.

NameDescription
System_CAPS_pubpropertyDigestMethod

Gets or sets the digest method Uniform Resource Identifier (URI) of the current Reference.

System_CAPS_pubpropertyDigestValue

Gets or sets the digest value of the current Reference.

System_CAPS_pubpropertyId

Gets or sets the ID of the current Reference.

System_CAPS_pubpropertyTransformChain

Gets the transform chain of the current Reference.

System_CAPS_pubpropertyType

Gets or sets the type of the object being signed.

System_CAPS_pubpropertyUri

Gets or sets the Uri of the current Reference.

NameDescription
System_CAPS_pubmethodAddTransform(Transform^)

Adds a Transform object to the list of transforms to be performed on the data before passing it to the digest algorithm.

System_CAPS_pubmethodEquals(Object^)

Determines whether the specified object is equal to the current object.(Inherited from Object.)

System_CAPS_protmethodFinalize()

Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection.(Inherited from Object.)

System_CAPS_pubmethodGetHashCode()

Serves as the default hash function. (Inherited from Object.)

System_CAPS_pubmethodGetType()

Gets the Type of the current instance.(Inherited from Object.)

System_CAPS_pubmethodGetXml()

Returns the XML representation of the Reference.

System_CAPS_pubmethodLoadXml(XmlElement^)

Loads a Reference state from an XML element.

System_CAPS_protmethodMemberwiseClone()

Creates a shallow copy of the current Object.(Inherited from Object.)

System_CAPS_pubmethodToString()

Returns a string that represents the current object.(Inherited from Object.)

The Reference object represents the <reference> element of an XML digital signature defined by the XML digital signature specification.

Use the Reference object to specify the following information:

  • The digest algorithm used to sign of the data object. This value is required.

  • The Uniform Resource Identifier (URI) of the data object to sign. The URI can specify a file path or specific elements within an XML document. This value is required.

  • A chain of transforms to apply before generating the digest. This value is optional.

  • The type of object to sign. This value is optional.

  • A unique identifier used to reference the current <reference> element. This value is optional.

For more information about the <reference> element, see the W3C specification at www.w3.org/TR/xmldsig-core/.

The following code example demonstrates how to generate and verify an enveloped XML signature using the Reference object.

//
// This example signs an XML file using an
// envelope signature. It then verifies the 
// signed XML.
//
#using <System.Security.dll>
#using <System.Xml.dll>

using namespace System;
using namespace System::Security::Cryptography;
using namespace System::Security::Cryptography::X509Certificates;
using namespace System::Security::Cryptography::Xml;
using namespace System::Text;
using namespace System::Xml;

// Sign an XML file and save the signature in a new file.
void SignXmlFile( String^ FileName, String^ SignedFileName, RSA^ Key )
{

   // Create a new XML document.
   XmlDocument^ doc = gcnew XmlDocument;

   // Format the document to ignore white spaces.
   doc->PreserveWhitespace = false;

   // Load the passed XML file using its name.
   doc->Load( gcnew XmlTextReader( FileName ) );

   // Create a SignedXml object.
   SignedXml^ signedXml = gcnew SignedXml( doc );

   // Add the key to the SignedXml document. 
   signedXml->SigningKey = Key;

   // Create a reference to be signed.
   Reference^ reference = gcnew Reference;
   reference->Uri = "";

   // Add an enveloped transformation to the reference.
   XmlDsigEnvelopedSignatureTransform^ env = gcnew XmlDsigEnvelopedSignatureTransform;
   reference->AddTransform( env );

   // Add the reference to the SignedXml object.
   signedXml->AddReference( reference );

   // Add an RSAKeyValue KeyInfo (optional; helps recipient find key to validate).
   KeyInfo^ keyInfo = gcnew KeyInfo;
   keyInfo->AddClause( gcnew RSAKeyValue( safe_cast<RSA^>(Key) ) );
   signedXml->KeyInfo = keyInfo;

   // Compute the signature.
   signedXml->ComputeSignature();

   // Get the XML representation of the signature and save
   // it to an XmlElement object.
   XmlElement^ xmlDigitalSignature = signedXml->GetXml();

   // Append the element to the XML document.
   doc->DocumentElement->AppendChild( doc->ImportNode( xmlDigitalSignature, true ) );
   if ( (doc->FirstChild)->GetType() == XmlDeclaration::typeid )
   {
      doc->RemoveChild( doc->FirstChild );
   }


   // Save the signed XML document to a file specified
   // using the passed string.
   XmlTextWriter^ xmltw = gcnew XmlTextWriter( SignedFileName,gcnew UTF8Encoding( false ) );
   doc->WriteTo( xmltw );
   xmltw->Close();
}


// Verify the signature of an XML file and return the result.
Boolean VerifyXmlFile( String^ Name )
{

   // Create a new XML document.
   XmlDocument^ xmlDocument = gcnew XmlDocument;

   // Format using white spaces.
   xmlDocument->PreserveWhitespace = true;

   // Load the passed XML file into the document. 
   xmlDocument->Load( Name );

   // Create a new SignedXml object and pass it
   // the XML document class.
   SignedXml^ signedXml = gcnew SignedXml( xmlDocument );

   // Find the "Signature" node and create a new
   // XmlNodeList object.
   XmlNodeList^ nodeList = xmlDocument->GetElementsByTagName( "Signature" );

   // Load the signature node.
   signedXml->LoadXml( safe_cast<XmlElement^>(nodeList->Item( 0 )) );

   // Check the signature and return the result.
   return signedXml->CheckSignature();
}


// Create example data to sign.
void CreateSomeXml( String^ FileName )
{

   // Create a new XmlDocument object.
   XmlDocument^ document = gcnew XmlDocument;

   // Create a new XmlNode object.
   XmlNode^ node = document->CreateNode( XmlNodeType::Element, "", "MyElement", "samples" );

   // Add some text to the node.
   node->InnerText = "Example text to be signed.";

   // Append the node to the document.
   document->AppendChild( node );

   // Save the XML document to the file name specified.
   XmlTextWriter^ xmltw = gcnew XmlTextWriter( FileName,gcnew UTF8Encoding( false ) );
   document->WriteTo( xmltw );
   xmltw->Close();
}

int main()
{
   try
   {

      // Generate a signing key.
      RSACryptoServiceProvider^ Key = gcnew RSACryptoServiceProvider;

      // Create an XML file to sign.
      CreateSomeXml( "Example.xml" );
      Console::WriteLine( "New XML file created." );

      // Sign the XML that was just created and save it in a 
      // new file.
      SignXmlFile( "Example.xml", "SignedExample.xml", Key );
      Console::WriteLine( "XML file signed." );

      // Verify the signature of the signed XML.
      Console::WriteLine( "Verifying signature..." );
      bool result = VerifyXmlFile( "SignedExample.xml" );

      // Display the results of the signature verification to
      // the console.
      if ( result )
      {
         Console::WriteLine( "The XML signature is valid." );
      }
      else
      {
         Console::WriteLine( "The XML signature is not valid." );
      }
   }
   catch ( CryptographicException^ e ) 
   {
      Console::WriteLine( e->Message );
   }

}

.NET Framework
Available since 1.1

Any public static ( Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Return to top
Show: