AsymmetricKeyAlgorithmProvider Class

Reference

Definition

Namespace:: Windows.Security.Cryptography.Core

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Edit

Represents a provider of asymmetric (public) key algorithms. For more information, see Cryptographic keys.

public ref class AsymmetricKeyAlgorithmProvider sealed

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class AsymmetricKeyAlgorithmProvider final

[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public sealed class AsymmetricKeyAlgorithmProvider

Public NotInheritable Class AsymmetricKeyAlgorithmProvider

Inheritance: Object Platform::Object IInspectable AsymmetricKeyAlgorithmProvider

Attributes: ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Windows requirements

Device family	Windows 10 (introduced in 10.0.10240.0)
API contract	Windows.Foundation.UniversalApiContract (introduced in v1.0)

Examples

Because asymmetric cryptography is much slower than symmetric cryptography, it is seldom used to encrypt large amounts of data directly. Instead, it is typically used in the following manner to encrypt keys.

Alice requires that Bob send her only encrypted messages.
Alice creates a private/public key pair, keeps her private key secret and publishes her public key.
Bob has a message he wants to send to Alice.
Bob creates a symmetric key.
Bob uses his new symmetric key to encrypt his message to Alice.
Bob uses Alice's public key to encrypt his symmetric key.
Bob sends the encrypted message and the encrypted symmetric key to Alice (enveloped).
Alice uses her private key (from the private/public pair) to decrypt Bob’s symmetric key.
Alice uses Bob's symmetric key to decrypt the message. The aspects of the preceding process that can be addressed in code are shown by the following example.


using Windows.Security.Cryptography;
using Windows.Security.Cryptography.Core;
using Windows.Storage.Streams;

namespace SampleAsymmetricKeyAlgorithmProvider
{
    sealed partial class AsymmetricKeyAlgorithmApp : Application
    {
        static IBuffer buffKeyPair;

        public AsymmetricKeyAlgorithmApp()
        {
            // Initialize the application.
            this.InitializeComponent();

            // Create a symmetric session key.
            String strSymmetricAlgName = SymmetricAlgorithmNames.AesCbc;
            UInt32 symmetricKeyLength = 32;
            IBuffer buffSessionKey;
            this.SampleCreateSymmetricSessionKey(
                strSymmetricAlgName, 
                symmetricKeyLength, 
                out buffSessionKey);

            // Create an asymmetric key pair.
            String strAsymmetricAlgName = AsymmetricAlgorithmNames.RsaPkcs1;
            UInt32 asymmetricKeyLength = 512;
            IBuffer buffPublicKey;
            this.SampleCreateAsymmetricKeyPair(
                strAsymmetricAlgName, 
                asymmetricKeyLength, 
                out buffPublicKey);
 
            // Encrypt the symmetric session key by using the asymmetric public key.
            IBuffer buffEncryptedSessionKey;
            this.SampleAsymmetricEncryptSessionKey(
                strAsymmetricAlgName,
                buffSessionKey,
                buffPublicKey,
                out buffEncryptedSessionKey);

            // Decrypt the symmetric session key by using the asymmetric private key
            // that corresponds to the public key used to encrypt the session key.
            this.SampleAsymmetricDecryptSessionKey(
                strAsymmetricAlgName,
                strSymmetricAlgName,
                buffEncryptedSessionKey);
        }

        public void SampleCreateSymmetricSessionKey(
            string strSymmetricAlgName,
            UInt32 keyLength,
            out IBuffer buffSessionKey)
        {
            // Open a symmetric algorithm provider for the specified algorithm.
            SymmetricKeyAlgorithmProvider objAlg = SymmetricKeyAlgorithmProvider.OpenAlgorithm(strSymmetricAlgName);

            // Create a symmetric session key.
            IBuffer keyMaterial = CryptographicBuffer.GenerateRandom(keyLength);
            CryptographicKey sessionKey = objAlg.CreateSymmetricKey(keyMaterial);

            buffSessionKey = keyMaterial;
        }

        public void SampleCreateAsymmetricKeyPair(
            String strAsymmetricAlgName,
            UInt32 keyLength,
            out IBuffer buffPublicKey)
        {
            // Open the algorithm provider for the specified asymmetric algorithm.
            AsymmetricKeyAlgorithmProvider objAlgProv = AsymmetricKeyAlgorithmProvider.OpenAlgorithm(strAsymmetricAlgName);

            // Demonstrate use of the AlgorithmName property (not necessary to create a key pair).
            String strAlgName = objAlgProv.AlgorithmName;

            // Create an asymmetric key pair.
            CryptographicKey keyPair = objAlgProv.CreateKeyPair(keyLength);

            // Export the public key to a buffer for use by others.
            buffPublicKey = keyPair.ExportPublicKey();

            // You should keep your private key (embedded in the key pair) secure. For  
            // the purposes of this example, however, we're just copying it into a
            // static class variable for later use during decryption.
            AsymmetricKeyAlgorithmApp.buffKeyPair = keyPair.Export();
        }
 
        public void SampleAsymmetricEncryptSessionKey(
            String strAsymmetricAlgName,
            IBuffer buffSessionKeyToEncrypt,
            IBuffer buffPublicKey,
            out IBuffer buffEncryptedSessionKey)
        {
            // Open the algorithm provider for the specified asymmetric algorithm.
            AsymmetricKeyAlgorithmProvider objAlgProv = AsymmetricKeyAlgorithmProvider.OpenAlgorithm(strAsymmetricAlgName);

            // Import the public key from a buffer.
            CryptographicKey publicKey = objAlgProv.ImportPublicKey(buffPublicKey);

            // Encrypt the session key by using the public key.
            buffEncryptedSessionKey = CryptographicEngine.Encrypt(publicKey, buffSessionKeyToEncrypt, null);
        }

        public void SampleAsymmetricDecryptSessionKey(
            String strAsymmetricAlgName,
            String strSymmetricAlgName,
            IBuffer buffEncryptedSessionKey)
        {
            // Open the algorithm provider for the specified asymmetric algorithm.
            AsymmetricKeyAlgorithmProvider objAsymmAlgProv = AsymmetricKeyAlgorithmProvider.OpenAlgorithm(strAsymmetricAlgName);

            // Import the public key from a buffer. You should keep your private key
            // secure. For the purposes of this example, however, the private key is
            // just stored in a static class variable.
            CryptographicKey keyPair = objAsymmAlgProv.ImportKeyPair(AsymmetricKeyAlgorithmApp.buffKeyPair);

            // Use the private key embedded in the key pair to decrypt the session key.
            IBuffer buffDecryptedSessionKey = CryptographicEngine.Decrypt(keyPair, buffEncryptedSessionKey, null);

            // Convert the decrypted session key into a CryptographicKey object that
            // can be used to decrypt the message that it previously encrypted (not shown).
            SymmetricKeyAlgorithmProvider objSymmAlgProv = SymmetricKeyAlgorithmProvider.OpenAlgorithm(strSymmetricAlgName);
            CryptographicKey sessionKey = objSymmAlgProv.CreateSymmetricKey(buffDecryptedSessionKey);
        }
    }
}

Remarks

You create an AsymmetricKeyAlgorithmProvider object by calling the static OpenAlgorithm method.

Properties

AlgorithmName

Gets the name of the open asymmetric algorithm.

Methods

CreateKeyPair(UInt32)	Creates a public/private key pair.
CreateKeyPairWithCurveName(String)	Creates a public/private key pair using an algorithmic curve name.
CreateKeyPairWithCurveParameters(Byte[])	Creates an asymmetric public/private key pair using curve parameters.
ImportKeyPair(IBuffer, CryptographicPrivateKeyBlobType)	Imports a public/private key pair from a buffer in the specified format.
ImportKeyPair(IBuffer)	Imports a public/private key pair from a buffer.
ImportPublicKey(IBuffer, CryptographicPublicKeyBlobType)	Imports a public key into a buffer for a specified format.
ImportPublicKey(IBuffer)	Imports a public key into a buffer.
OpenAlgorithm(String)	Creates an instance of the AsymmetricKeyAlgorithmProvider class and opens the specified algorithm for use.

Applies to

Share via