Asymmetric​Key​Algorithm​Provider Asymmetric​Key​Algorithm​Provider Asymmetric​Key​Algorithm​Provider Class

Definition

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

public sealed class AsymmetricKeyAlgorithmProvider : IAsymmetricKeyAlgorithmProvider, IAsymmetricKeyAlgorithmProvider2public sealed class AsymmetricKeyAlgorithmProvider : IAsymmetricKeyAlgorithmProvider, IAsymmetricKeyAlgorithmProvider2Public NotInheritable Class AsymmetricKeyAlgorithmProvider Implements IAsymmetricKeyAlgorithmProvider, IAsymmetricKeyAlgorithmProvider2
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

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

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

Properties

AlgorithmName AlgorithmName AlgorithmName

Gets the name of the open asymmetric algorithm.

public PlatForm::String AlgorithmName { get; }public string AlgorithmName { get; }Public ReadOnly Property AlgorithmName As string
Value
string string string

Algorithm name.

Attributes

Remarks

You must call OpenAlgorithm before calling the AlgorithmName property.

Methods

CreateKeyPair(UInt32) CreateKeyPair(UInt32) CreateKeyPair(UInt32)

Creates a public/private key pair.

public CryptographicKey CreateKeyPair(UInt32 keySize)public CryptographicKey CreateKeyPair(UInt32 keySize)Public Function CreateKeyPair(keySize As UInt32) As CryptographicKey
Parameters
keySize
System.UInt32 System.UInt32 System.UInt32

Size, in bits, of the key. Typical key sizes are 512, 1024, 2048, or 4096 bits.

Returns

Represents the asymmetric key pair.

Attributes

CreateKeyPairWithCurveName(String) CreateKeyPairWithCurveName(String) CreateKeyPairWithCurveName(String)

Creates a public/private key pair using a curve name.

public CryptographicKey CreateKeyPairWithCurveName(String curveName)public CryptographicKey CreateKeyPairWithCurveName(String curveName)Public Function CreateKeyPairWithCurveName(curveName As String) As CryptographicKey
Parameters
curveName
System.String System.String System.String

The name of the curve.

Returns

Represents the asymmetric key pair.

Attributes

CreateKeyPairWithCurveParameters(Byte[]) CreateKeyPairWithCurveParameters(Byte[]) CreateKeyPairWithCurveParameters(Byte[])

Creates a public/private key pair using curve parameters.

public CryptographicKey CreateKeyPairWithCurveParameters(Byte[] parameters)public CryptographicKey CreateKeyPairWithCurveParameters(Byte[] parameters)Public Function CreateKeyPairWithCurveParameters(parameters As Byte[]) As CryptographicKey
Parameters
parameters
System.Byte[] System.Byte[] System.Byte[]

The curve parameters.

Returns

Represents the asymmetric key pair.

Attributes

ImportKeyPair(IBuffer) ImportKeyPair(IBuffer) ImportKeyPair(IBuffer)

Imports a public/private key pair from a buffer.

public CryptographicKey ImportKeyPair(IBuffer keyBlob)public CryptographicKey ImportKeyPair(IBuffer keyBlob)Public Function ImportKeyPair(keyBlob As IBuffer) As CryptographicKey
Parameters
keyBlob
IBuffer IBuffer IBuffer

Buffer that contains the key pair to import.

Returns

Represents the imported key pair.

Attributes

ImportKeyPair(IBuffer, CryptographicPrivateKeyBlobType) ImportKeyPair(IBuffer, CryptographicPrivateKeyBlobType) ImportKeyPair(IBuffer, CryptographicPrivateKeyBlobType)

Imports a public/private key pair from a buffer in the specified format.

public CryptographicKey ImportKeyPair(IBuffer keyBlob, CryptographicPrivateKeyBlobType BlobType)public CryptographicKey ImportKeyPair(IBuffer keyBlob, CryptographicPrivateKeyBlobType BlobType)Public Function ImportKeyPair(keyBlob As IBuffer, BlobType As CryptographicPrivateKeyBlobType) As CryptographicKey
Parameters
keyBlob
IBuffer IBuffer IBuffer

Buffer that contains the key pair to import.

BlobType
CryptographicPrivateKeyBlobType CryptographicPrivateKeyBlobType CryptographicPrivateKeyBlobType

A CryptographicPrivateKeyBlobType enumeration value that specifies information about the private key contained in the keyBlob buffer. The default value is Pkcs8RawPrivateKeyInfo.

Returns

Represents the imported key pair.

Attributes

ImportPublicKey(IBuffer) ImportPublicKey(IBuffer) ImportPublicKey(IBuffer)

Imports a public key into a buffer.

public CryptographicKey ImportPublicKey(IBuffer keyBlob)public CryptographicKey ImportPublicKey(IBuffer keyBlob)Public Function ImportPublicKey(keyBlob As IBuffer) As CryptographicKey
Parameters
keyBlob
IBuffer IBuffer IBuffer

Buffer that contains the key to import.

Returns

Represents the imported key.

Attributes

ImportPublicKey(IBuffer, CryptographicPublicKeyBlobType) ImportPublicKey(IBuffer, CryptographicPublicKeyBlobType) ImportPublicKey(IBuffer, CryptographicPublicKeyBlobType)

Imports a public key into a buffer for a specified format.

public CryptographicKey ImportPublicKey(IBuffer keyBlob, CryptographicPublicKeyBlobType BlobType)public CryptographicKey ImportPublicKey(IBuffer keyBlob, CryptographicPublicKeyBlobType BlobType)Public Function ImportPublicKey(keyBlob As IBuffer, BlobType As CryptographicPublicKeyBlobType) As CryptographicKey
Parameters
keyBlob
IBuffer IBuffer IBuffer

Buffer that contains the key to import.

BlobType
CryptographicPublicKeyBlobType CryptographicPublicKeyBlobType CryptographicPublicKeyBlobType

A CryptographicPublicKeyBlobType enumeration value that specifies the format of the public key contained in the keyBlob buffer. The default value is X509SubjectPublicKeyInfo.

Returns

Represents the imported key.

Attributes

OpenAlgorithm(String) OpenAlgorithm(String) OpenAlgorithm(String)

Creates an instance of the AsymmetricKeyAlgorithmProvider class and opens the specified algorithm for use.

public static AsymmetricKeyAlgorithmProvider OpenAlgorithm(String algorithm)public static AsymmetricKeyAlgorithmProvider OpenAlgorithm(String algorithm)Public Static Function OpenAlgorithm(algorithm As String) As AsymmetricKeyAlgorithmProvider
Parameters
algorithm
System.String System.String System.String

Algorithm name.

Returns
Attributes

Remarks

Use the static properties in the AsymmetricAlgorithmNames class to specify the name of the algorithm to open.