ECDiffieHellmanCng Class
Updated: March 2011
Provides a Cryptography Next Generation (CNG) implementation of the Elliptic Curve Diffie-Hellman (ECDH) algorithm. This class is used to perform cryptographic operations.
Assembly: System.Core (in System.Core.dll)
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 ECDiffieHellmanCng class enables two parties to exchange private key material even if they are communicating through a public channel. Both parties can calculate the same secret value, which is referred to as the secret agreement in the managed Diffie-Hellman classes. The secret agreement can then be used for a variety of purposes, including as a symmetric key. However, instead of exposing the secret agreement directly, the ECDiffieHellmanCng class does some post-processing on the agreement before providing the value. This post processing is referred to as the key derivation function (KDF); you can select which KDF you want to use and set its parameters through a set of properties on the instance of the Diffie-Hellman object.
Key derivation function | Properties |
|---|---|
HashAlgorithm - The hash algorithm that is used to process the secret agreement. SecretPrepend - An optional byte array to prepend to the secret agreement before hashing it. SecretAppend - An optional byte array to append to the secret agreement before hashing it. | |
HashAlgorithm - The hash algorithm that is used to process the secret agreement. SecretPrepend- An optional byte array to prepend to the secret agreement before hashing it. SecretAppend - An optional byte array to append to the secret agreement before hashing it. | |
Label - The label for key derivation. Seed - The seed for key derivation. |
The result of passing the secret agreement through the key derivation function is a byte array that may be used as key material for your application. The number of bytes of key material generated is dependent on the key derivation function; for example, SHA-256 will generate 256 bits of key material, whereas SHA-512 will generate 512 bits of key material.The basic flow of an ECDH key exchange is as follows:
Alice and Bob create a key pair to use for the Diffie-Hellman key exchange operation
Alice and Bob configure the KDF using parameters the agree on.
Alice sends Bob her public key.
Bob sends Alice his public key.
Alice and Bob use each other's public keys to generate the secret agreement, and apply the KDF to the secret agreement to generate key material.
The following example shows how to use the ECDiffieHellmanCng class to establish a key exchange and how to use that key to encrypt a message that can be sent over a public channel and decrypted by the receiver.
Imports System Imports System.IO Imports System.Security.Cryptography Imports System.Text Class Alice Public Shared alicePublicKey() As Byte Public Shared Sub Main(ByVal args() As String) Using alice As New ECDiffieHellmanCng() alice.KeyDerivationFunction = ECDiffieHellmanKeyDerivationFunction.Hash alice.HashAlgorithm = CngAlgorithm.Sha256 alicePublicKey = alice.PublicKey.ToByteArray() Dim bob As New Bob() Dim k As CngKey = CngKey.Import(bob.bobPublicKey, CngKeyBlobFormat.EccPublicBlob) Dim aliceKey As Byte() = alice.DeriveKeyMaterial(CngKey.Import(bob.bobPublicKey, CngKeyBlobFormat.EccPublicBlob)) Dim encryptedMessage As Byte() = Nothing Dim iv As Byte() = Nothing Send(aliceKey, "Secret message", encryptedMessage, iv) bob.Receive(encryptedMessage, iv) End Using End Sub 'Main Private Shared Sub Send(ByVal key() As Byte, ByVal secretMessage As String, ByRef encryptedMessage() As Byte, ByRef iv() As Byte) Using aes As New AesCryptoServiceProvider() aes.Key = key iv = aes.IV ' Encrypt the message Using ciphertext As New MemoryStream() Using cs As New CryptoStream(ciphertext, aes.CreateEncryptor(), CryptoStreamMode.Write) Dim plaintextMessage As Byte() = Encoding.UTF8.GetBytes(secretMessage) cs.Write(plaintextMessage, 0, plaintextMessage.Length) cs.Close() encryptedMessage = ciphertext.ToArray() End Using End Using End Using End Sub 'Send End Class 'Alice Public Class Bob Public bobPublicKey() As Byte Private bobKey() As Byte Public Sub New() Using bob As New ECDiffieHellmanCng() bob.KeyDerivationFunction = ECDiffieHellmanKeyDerivationFunction.Hash bob.HashAlgorithm = CngAlgorithm.Sha256 bobPublicKey = bob.PublicKey.ToByteArray() bobKey = bob.DeriveKeyMaterial(CngKey.Import(Alice.alicePublicKey, CngKeyBlobFormat.EccPublicBlob)) End Using End Sub 'New Public Sub Receive(ByVal encryptedMessage() As Byte, ByVal iv() As Byte) Using aes As New AesCryptoServiceProvider() aes.Key = bobKey aes.IV = iv ' Decrypt the message Using plaintext As New MemoryStream() Using cs As New CryptoStream(plaintext, aes.CreateDecryptor(), CryptoStreamMode.Write) cs.Write(encryptedMessage, 0, encryptedMessage.Length) cs.Close() Dim message As String = Encoding.UTF8.GetString(plaintext.ToArray()) Console.WriteLine(message) End Using End Using End Using End Sub 'Receive End Class 'Bob
System.Security.Cryptography.AsymmetricAlgorithm
System.Security.Cryptography.ECDiffieHellman
System.Security.Cryptography.ECDiffieHellmanCng
Windows 7, Windows Vista, Windows Server 2008 R2, Windows Server 2008
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.
Note: