KeyInfo Class
Represents an XML digital signature or XML encryption <KeyInfo> element.
Assembly: System.Security (in System.Security.dll)
The KeyInfo type exposes the following members.
| Name | Description | |
|---|---|---|
![]() | Count | Gets the number of KeyInfoClause objects contained within the KeyInfo object. |
![]() | Id | Gets or sets the KeyInfo ID. |
| Name | Description | |
|---|---|---|
![]() | AddClause | Adds a KeyInfoClause that represents a particular type of KeyInfo information to the KeyInfo object. |
![]() | Equals(Object) | Determines whether the specified Object is equal to the current Object. (Inherited from Object.) |
![]() | Finalize | Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.) |
![]() | GetEnumerator() | Returns an enumerator of the KeyInfoClause objects in the KeyInfo object. |
![]() | GetEnumerator(Type) | Returns an enumerator of the KeyInfoClause objects of the specified type in the KeyInfo object. |
![]() | GetHashCode | Serves as a hash function for a particular type. (Inherited from Object.) |
![]() | GetType | Gets the Type of the current instance. (Inherited from Object.) |
![]() | GetXml | Returns the XML representation of the KeyInfo object. |
![]() | LoadXml | Loads a KeyInfo state from an XML element. |
![]() | MemberwiseClone | Creates a shallow copy of the current Object. (Inherited from Object.) |
![]() | ToString | Returns a string that represents the current object. (Inherited from Object.) |
| Name | Description | |
|---|---|---|
![]() | AsParallel | Enables parallelization of a query. (Defined by ParallelEnumerable.) |
![]() | AsQueryable | Converts an IEnumerable to an IQueryable. (Defined by Queryable.) |
![]() | Cast<TResult> | Converts the elements of an IEnumerable to the specified type. (Defined by Enumerable.) |
![]() | OfType<TResult> | Filters the elements of an IEnumerable based on a specified type. (Defined by Enumerable.) |
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/.
Note |
|---|
The HostProtectionAttribute attribute applied to this type or member has the following Resources property value: MayLeakOnAbort. The HostProtectionAttribute does not affect desktop applications (which are typically started by double-clicking an icon, typing a command, or entering a URL in a browser). For more information, see the HostProtectionAttribute class or SQL Server Programming and Host Protection Attributes. |
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; }
Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows XP SP2 x64 Edition, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2
The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.
