This documentation is archived and is not being maintained.

KeyInfo Class

Represents an XML digital signature or XML encryption <KeyInfo> element.

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

public ref class KeyInfo : IEnumerable

The KeyInfo class represents key information in XML digital signing and encryption.

The KeyInfo class enables you to imbed key-related information intended to help identify the key necessary for validating or decrypting the XML document. Multiple types of key-related information can be included within a single KeyInfo; each type of key-related information has an associated class derived from KeyInfoClause.

For more information about the <KeyInfo> element, see the XMLDSIG specification, which is available from the W3C at www.w3.org/TR/xmldsig-core/, or see the XML encryption specification, which is available from the W3C at www.w3.org/TR/xmlenc-core/.

The following code example uses the KeyInfo object when signing a resource represented by a Universal Resource Identifier (URI). This example saves the signature in a new file.

// 
// This example signs a file specified by a URI  
// using a detached 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::Xml;
using namespace System::Text;
using namespace System::Xml;

// Sign an XML file and save the signature in a new file. 
void SignDetachedResource( String^ URIString, String^ XmlSigFileName, RSA^ Key )
{

   // Create a SignedXml object.
   SignedXml^ signedXml = gcnew SignedXml;

   // Assign the key to the SignedXml object.
   signedXml->SigningKey = Key;

   // Create a reference to be signed.
   Reference^ reference = gcnew Reference;

   // Add the passed URI to the reference object.
   reference->Uri = URIString;

   // 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();

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


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

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

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

   // Create a new SignedXMl object.
   SignedXml^ signedXml = gcnew SignedXml;

   // 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();
}



[STAThread]
int main()
{
   array<String^>^args = Environment::GetCommandLineArgs();

   // The URI to sign.
   String^ resourceToSign = "http://www.microsoft.com";

   // The name of the file to which to save the XML signature.
   String^ XmlFileName = "xmldsig.xml";
   try
   {

      // Generate a signing key.
      RSACryptoServiceProvider^ Key = gcnew RSACryptoServiceProvider;
      Console::WriteLine( "Signing: {0}", resourceToSign );

      // Sign the detached resourceand save the signature in an XML file.
      SignDetachedResource( resourceToSign, XmlFileName, Key );
      Console::WriteLine( "XML signature was succesfully computed and saved to {0}.", XmlFileName );

      // Verify the signature of the signed XML.
      Console::WriteLine( "Verifying signature..." );

      //Verify the XML signature in the XML file. 
      bool result = VerifyDetachedSignature( XmlFileName );

      // 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 );
   }

}

The following code example uses the KeyInfo object when signing an XML document. This example saves the signature in a new file.

// 
// 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 );
   }

}

The following code example uses the KeyInfo object when encrypting an XML document. This example embeds an encrypted key within the encrypted XML document.

#using <System.Xml.dll>
#using <System.Security.dll>
#using <System.dll>

using namespace System;
using namespace System::Xml;
using namespace System::Security::Cryptography;
using namespace System::Security::Cryptography::Xml;
static void Encrypt( XmlDocument^ Doc, String^ ElementToEncrypt, RSA^ Alg, String^ KeyName )
{

   // Check the arguments. 
   if ( Doc == nullptr )
      throw gcnew ArgumentNullException( L"Doc" );

   if ( ElementToEncrypt == nullptr )
      throw gcnew ArgumentNullException( L"ElementToEncrypt" );

   if ( Alg == nullptr )
      throw gcnew ArgumentNullException( L"Alg" );


   //////////////////////////////////////////////// 
   // Find the specified element in the XmlDocument 
   // object and create a new XmlElemnt object. 
   ////////////////////////////////////////////////
   XmlElement^ elementToEncrypt = dynamic_cast<XmlElement^>(Doc->GetElementsByTagName( ElementToEncrypt )->Item( 0 ));

   // Throw an XmlException if the element was not found. 
   if ( elementToEncrypt == nullptr )
   {
      throw gcnew XmlException( L"The specified element was not found" );
   }


   ////////////////////////////////////////////////// 
   // Create a new instance of the EncryptedXml class 
   // and use it to encrypt the XmlElement with the 
   // a new random symmetric key. 
   ////////////////////////////////////////////////// 
   // Create a 256 bit Rijndael key.
   RijndaelManaged^ sessionKey = gcnew RijndaelManaged;
   sessionKey->KeySize = 256;
   EncryptedXml^ eXml = gcnew EncryptedXml;
   array<Byte>^encryptedElement = eXml->EncryptData( elementToEncrypt, sessionKey, false );

   //////////////////////////////////////////////// 
   // Construct an EncryptedData object and populate 
   // it with the desired encryption information. 
   ////////////////////////////////////////////////
   EncryptedData^ edElement = gcnew EncryptedData;
   edElement->Type = EncryptedXml::XmlEncElementUrl;

   // Create an EncryptionMethod element so that the 
   // receiver knows which algorithm to use for decryption.
   edElement->EncryptionMethod = gcnew EncryptionMethod( EncryptedXml::XmlEncAES256Url );

   // Encrypt the session key and add it to an EncryptedKey element.
   EncryptedKey^ ek = gcnew EncryptedKey;
   array<Byte>^encryptedKey = EncryptedXml::EncryptKey( sessionKey->Key, Alg, false );
   ek->CipherData = gcnew CipherData( encryptedKey );
   ek->EncryptionMethod = gcnew EncryptionMethod( EncryptedXml::XmlEncRSA15Url );

   // Set the KeyInfo element to specify the 
   // name of the RSA key. 
   // Create a new KeyInfo element.
   edElement->KeyInfo = gcnew KeyInfo;

   // Create a new KeyInfoName element.
   KeyInfoName^ kin = gcnew KeyInfoName;

   // Specify a name for the key.
   kin->Value = KeyName;

   // Add the KeyInfoName element to the 
   // EncryptedKey object.
   ek->KeyInfo->AddClause( kin );

   // Add the encrypted key to the 
   // EncryptedData object.
   edElement->KeyInfo->AddClause( gcnew KeyInfoEncryptedKey( ek ) );

   // Add the encrypted element data to the 
   // EncryptedData object.
   edElement->CipherData->CipherValue = encryptedElement;

   //////////////////////////////////////////////////// 
   // Replace the element from the original XmlDocument 
   // object with the EncryptedData element. 
   ////////////////////////////////////////////////////
   EncryptedXml::ReplaceElement( elementToEncrypt, edElement, false );
}

static void Decrypt( XmlDocument^ Doc, RSA^ Alg, String^ KeyName )
{

   // Check the arguments. 
   if ( Doc == nullptr )
      throw gcnew ArgumentNullException( L"Doc" );

   if ( Alg == nullptr )
      throw gcnew ArgumentNullException( L"Alg" );

   if ( KeyName == nullptr )
      throw gcnew ArgumentNullException( L"KeyName" );


   // Create a new EncryptedXml object.
   EncryptedXml^ exml = gcnew EncryptedXml( Doc );

   // Add a key-name mapping. 
   // This method can only decrypt documents 
   // that present the specified key name.
   exml->AddKeyNameMapping( KeyName, Alg );

   // Decrypt the element.
   exml->DecryptDocument();
}

int main()
{

   // Create an XmlDocument object.
   XmlDocument^ xmlDoc = gcnew XmlDocument;

   // Load an XML file into the XmlDocument object. 
   try
   {
      xmlDoc->PreserveWhitespace = true;
      xmlDoc->Load( L"test.xml" );
   }
   catch ( Exception^ e )
   {
      Console::WriteLine( e->Message );
      return 0;
   }


   // Create a new RSA key.  This key will encrypt a symmetric key, 
   // which will then be imbedded in the XML document.
   RSA^ rsaKey = gcnew RSACryptoServiceProvider;
   try
   {

      // Encrypt the "creditcard" element.
      Encrypt( xmlDoc, L"creditcard", rsaKey, L"rsaKey" );

      // Display the encrypted XML to the console.
      Console::WriteLine( L"Encrypted XML:" );
      Console::WriteLine();
      Console::WriteLine( xmlDoc->OuterXml );
	  xmlDoc->Save( L"test.xml" );

      // Decrypt the "creditcard" element.
      Decrypt( xmlDoc, rsaKey, L"rsaKey" );

      // Display the encrypted XML to the console.
      Console::WriteLine();
      Console::WriteLine( L"Decrypted XML:" );
      Console::WriteLine();
      Console::WriteLine( xmlDoc->OuterXml );
	  xmlDoc->Save( L"test.xml" );
   }
   catch ( Exception^ e )
   {
      Console::WriteLine( e->Message );
   }
   finally
   {

      // Clear the RSA key.
      rsaKey->Clear();
   }

   return 1;
}

The following code example uses the KeyInfo object when encrypting an XML document. This example maps a name to a symmetric key to identify it to the decryption method.

#using <System.Security.dll>
#using <System.dll>
#using <System.Xml.dll>

using namespace System;
using namespace System::Xml;
using namespace System::Security::Cryptography;
using namespace System::Security::Cryptography::Xml;
static void Encrypt( XmlDocument^ Doc, String^ ElementToEncrypt, SymmetricAlgorithm^ Alg, String^ KeyName )
{

   // Check the arguments. 
   if ( Doc == nullptr )
      throw gcnew ArgumentNullException( L"Doc" );

   if ( ElementToEncrypt == nullptr )
      throw gcnew ArgumentNullException( L"ElementToEncrypt" );

   if ( Alg == nullptr )
      throw gcnew ArgumentNullException( L"Alg" );


   //////////////////////////////////////////////// 
   // Find the specified element in the XmlDocument 
   // object and create a new XmlElemnt object. 
   ////////////////////////////////////////////////
   XmlElement^ elementToEncrypt = dynamic_cast<XmlElement^>(Doc->GetElementsByTagName( ElementToEncrypt )->Item( 0 ));

   // Throw an XmlException if the element was not found. 
   if ( elementToEncrypt == nullptr )
   {
      throw gcnew XmlException( L"The specified element was not found" );
   }


   ////////////////////////////////////////////////// 
   // Create a new instance of the EncryptedXml class 
   // and use it to encrypt the XmlElement with the 
   // symmetric key. 
   //////////////////////////////////////////////////
   EncryptedXml^ eXml = gcnew EncryptedXml;
   array<Byte>^encryptedElement = eXml->EncryptData( elementToEncrypt, Alg, false );

   //////////////////////////////////////////////// 
   // Construct an EncryptedData object and populate 
   // it with the desired encryption information. 
   ////////////////////////////////////////////////
   EncryptedData^ edElement = gcnew EncryptedData;
   edElement->Type = EncryptedXml::XmlEncElementUrl;

   // Create an EncryptionMethod element so that the 
   // receiver knows which algorithm to use for decryption. 
   // Determine what kind of algorithm is being used and 
   // supply the appropriate URL to the EncryptionMethod element.
   String^ encryptionMethod = nullptr;
   if ( dynamic_cast<TripleDES^>(Alg) )
   {
      encryptionMethod = EncryptedXml::XmlEncTripleDESUrl;
   }
   else 
   if ( dynamic_cast<DES^>(Alg) )
   {
      encryptionMethod = EncryptedXml::XmlEncDESUrl;
   }
   else 
   if ( dynamic_cast<Rijndael^>(Alg) )
   {
      switch ( Alg->KeySize )
      {
         case 128:
            encryptionMethod = EncryptedXml::XmlEncAES128Url;
            break;

         case 192:
            encryptionMethod = EncryptedXml::XmlEncAES192Url;
            break;

         case 256:
            encryptionMethod = EncryptedXml::XmlEncAES256Url;
            break;
      }
   }
   else
   {

      // Throw an exception if the transform is not in the previous categories 
      throw gcnew CryptographicException( L"The specified algorithm is not supported for XML Encryption." );
   }



   edElement->EncryptionMethod = gcnew EncryptionMethod( encryptionMethod );

   // Set the KeyInfo element to specify the 
   // name of a key. 
   // Create a new KeyInfo element.
   edElement->KeyInfo = gcnew KeyInfo;

   // Create a new KeyInfoName element.
   KeyInfoName^ kin = gcnew KeyInfoName;

   // Specify a name for the key.
   kin->Value = KeyName;

   // Add the KeyInfoName element.
   edElement->KeyInfo->AddClause( kin );

   // Add the encrypted element data to the 
   // EncryptedData object.
   edElement->CipherData->CipherValue = encryptedElement;

   //////////////////////////////////////////////////// 
   // Replace the element from the original XmlDocument 
   // object with the EncryptedData element. 
   ////////////////////////////////////////////////////
   EncryptedXml::ReplaceElement( elementToEncrypt, edElement, false );
}

static void Decrypt( XmlDocument^ Doc, SymmetricAlgorithm^ Alg, String^ KeyName )
{

   // Check the arguments. 
   if ( Doc == nullptr )
      throw gcnew ArgumentNullException( L"Doc" );

   if ( Alg == nullptr )
      throw gcnew ArgumentNullException( L"Alg" );

   if ( KeyName == nullptr )
      throw gcnew ArgumentNullException( L"KeyName" );


   // Create a new EncryptedXml object.
   EncryptedXml^ exml = gcnew EncryptedXml( Doc );

   // Add a key-name mapping. 
   // This method can only decrypt documents 
   // that present the specified key name.
   exml->AddKeyNameMapping( KeyName, Alg );

   // Decrypt the element.
   exml->DecryptDocument();
}

int main()
{

   // Create an XmlDocument object.
   XmlDocument^ xmlDoc = gcnew XmlDocument;

   // Load an XML file into the XmlDocument object. 
   try
   {
      xmlDoc->PreserveWhitespace = true;
      xmlDoc->Load( L"test.xml" );
   }
   catch ( Exception^ e )
   {
      Console::WriteLine( e->Message );
      return 0;
   }


   // Create a new TripleDES key.
   TripleDESCryptoServiceProvider^ tDESkey = gcnew TripleDESCryptoServiceProvider;
   try
   {

      // Encrypt the "creditcard" element.
      Encrypt( xmlDoc, L"creditcard", tDESkey, L"tDESKey" );

      // Display the encrypted XML to the console.
      Console::WriteLine( L"Encrypted XML:" );
      Console::WriteLine();
      Console::WriteLine( xmlDoc->OuterXml );

      // Decrypt the "creditcard" element.
      Decrypt( xmlDoc, tDESkey, L"tDESKey" );

      // Display the encrypted XML to the console.
      Console::WriteLine();
      Console::WriteLine( L"Decrypted XML:" );
      Console::WriteLine();
      Console::WriteLine( xmlDoc->OuterXml );
   }
   catch ( Exception^ e )
   {
      Console::WriteLine( e->Message );
   }
   finally
   {

      // Clear the TripleDES key.
      tDESkey->Clear();
   }
   return 1;
}

System::Object
  System.Security.Cryptography.Xml::KeyInfo

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

Windows 7, Windows Vista, Windows XP SP2, Windows XP Media Center Edition, Windows XP Professional x64 Edition, Windows XP Starter Edition, Windows Server 2008 R2, Windows Server 2008, Windows Server 2003, Windows Server 2000 SP4, Windows Millennium Edition, Windows 98

The .NET Framework and .NET Compact Framework do not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

.NET Framework

Supported in: 3.5, 3.0, 2.0, 1.1, 1.0
Show: