Diffie-Hellman Keys
- Generating Diffie-Hellman Keys
- Exchanging Diffie-Hellman Keys
- Exporting a Diffie-Hellman Private Key
- Example Code
Generating Diffie-Hellman Keys
To generate a Diffie-Hellman key, perform the following steps:
Call the CryptAcquireContext function to get a handle to the Microsoft Diffie-Hellman Cryptographic Provider.
Generate the new key. There are two ways to accomplish this—by having CryptoAPI generate all new values for G, P, and X or by using existing values for G and P, and generating a new value for X.
To generate the key by generating all new values
- Call the CryptGenKey function, passing either CALG_DH_SF (store and forward) or CALG_DH_EPHEM (ephemeral) in the Algid parameter. The key will be generated using new, random values for G and P, a newly calculated value for X, and its handle will be returned in the phKey parameter.
- The new key is now ready for use. The values of G and P must be sent to the recipient along with the key (or sent by some other method) when doing a key exchange.
To generate the key by using predefined values for G and P
- Call CryptGenKey passing either CALG_DH_SF (store and forward) or CALG_DH_EPHEM (ephemeral) in the Algid parameter and CRYPT_PREGEN for the dwFlags parameter. A key handle will be generated and returned in the phKey parameter.
- Initialize a CRYPT_DATA_BLOB structure with the pbData member set to the P value. The BLOB contains no header information and the pbData member is in little-endian format.
- The value of P is set by calling the CryptSetKeyParam function, passing the key handle retrieved in step a in the hKey parameter, the KP_P flag in the dwParam parameter, and a pointer to the structure that contains the value of P in the pbData parameter.
- Initialize a CRYPT_DATA_BLOB structure with the pbData member set to the G value. The BLOB contains no header information and the pbData member is in little-endian format.
- The value of G is set by calling the CryptSetKeyParam function, passing the key handle retrieved in step a in the hKey parameter, the KP_G flag in the dwParam parameter, and a pointer to the structure that contains the value of G in the pbData parameter.
- The value of X is generated by calling the CryptSetKeyParam function, passing the key handle retrieved in step a in the hKey parameter, the KP_X flag in the dwParam parameter, and NULL in the pbData parameter.
- If all the function calls succeeded, the Diffie-Hellman public key is ready for use.
When the key is no longer needed, destroy it by passing the key handle to the CryptDestroyKey function.
If CALG_DH_SF was specified in the previous procedures, the key values are persisted to storage with each call to CryptSetKeyParam. The G and P values can then be retrieved by using the CryptGetKeyParam function. Some CSPs may have hard-coded G and P values. In this case a NTE_FIXEDPARAMETER error will be returned if CryptSetKeyParam is called with KP_G or KP_P specified in the dwParam parameter. If CryptDestroyKey is called, the handle to the key is destroyed, but the key values are retained in the CSP. However, if CALG_DH_EPHEM was specified, the handle to the key is destroyed, and all values are cleared from the CSP.
Exchanging Diffie-Hellman Keys
The purpose of the Diffie-Hellman algorithm is to make it possible for two or more parties to create and share an identical, secret session key by sharing information over a network that is not secure. The information that gets shared over the network is in the form of a couple of constant values and a Diffie-Hellman public key. The process used by two key-exchange parties is as follows:
- Both parties agree to the Diffie-Hellman parameters which are a prime number (P) and a generator number (G).
- Party 1 sends its Diffie-Hellman public key to party 2.
- Party 2 computes the secret session key by using the information contained in its private key and party 1's public key.
- Party 2 sends its Diffie-Hellman public key to party 1.
- Party 1 computes the secret session key by using the information contained in its private key and party 2's public key.
- Both parties now have the same session key, which can be used for encrypting and decrypting data. The steps necessary for this are shown in the following procedure.
To prepare a Diffie-Hellman public key for transmission
- Call the CryptAcquireContext function to get a handle to the Microsoft Diffie-Hellman Cryptographic Provider.
- Create a Diffie-Hellman key by calling the CryptGenKey function to create a new key, or by calling the CryptGetUserKey function to retrieve an existing key.
- Get the size needed to hold the Diffie-Hellman key BLOB by calling the CryptExportKey, passing NULL for the pbData parameter. The required size will be returned in pdwDataLen.
- Allocate memory for the key BLOB.
- Create a Diffie-Hellman public key BLOB by calling the CryptExportKey function, passing PUBLICKEYBLOB in the dwBlobType parameter and the handle to the Diffie-Hellman key in the hKey parameter. This function call causes the calculation of the public key value, (G^X) mod P.
- If all the preceding function calls were successful, the Diffie-Hellman public key BLOB is now ready to be encoded and transmitted.
To import a Diffie-Hellman public key and calculate the secret session key
- Call the CryptAcquireContext function to get a handle to the Microsoft Diffie-Hellman Cryptographic Provider.
- Create a Diffie-Hellman key by calling the CryptGenKey function to create a new key, or by calling the CryptGetUserKey function to retrieve an existing key.
- To import the Diffie-Hellman public key into the CSP, call the CryptImportKey function, passing a pointer to the public key BLOB in the pbData parameter, the length of the BLOB in the dwDataLen parameter, and the handle to the Diffie-Hellman key in the hPubKey parameter. This causes the calculation, (Y^X) mod P, to be performed, thus creating the shared, secret key and completing the key exchange. This function call returns a handle to the new, secret, session key in the hKey parameter.
- At this point, the imported Diffie-Hellman is of type CALG_AGREEDKEY_ANY. Before the key can be used, it must be converted into a session key type. This is accomplished by calling the CryptSetKeyParam function with dwParam set to KP_ALGID and with pbData set to a pointer to a ALG_ID value that represents a session key, such as CALG_RC4. The key must be converted before using the shared key in the CryptEncrypt or CryptDecrypt function. Calls made to either of these functions prior to converting the key type will fail.
- The secret session key is now ready to be used for encryption or decryption.
- When the key is no longer needed, destroy the key handle by calling the CryptDestroyKey function.
Exporting a Diffie-Hellman Private Key
To export a Diffie-Hellman private key, perform the following steps:
- Call the CryptAcquireContext function to get a handle to the Microsoft Diffie-Hellman Cryptographic Provider.
- Create a Diffie-Hellman key by calling the CryptGenKey function to create a new key, or by calling the CryptGetUserKey function to retrieve an existing key.
- Create a Diffie-Hellman private key BLOB by calling the CryptExportKey function, passing PRIVATEKEYBLOB in the dwBlobType parameter and the handle to the Diffie-Hellman key in the hKey parameter.
- When the key handle is no longer needed, call the CryptDestroyKey function to destroy the key handle.
Example Code
The following example shows how to create, export, import, and use a Diffie-Hellman key to perform a key exchange.
#include <tchar.h>
#include <windows.h>
#include <wincrypt.h>
#pragma comment(lib, "crypt32.lib")
// The key size, in bits.
#define DHKEYSIZE 512
// Prime in little-endian format.
static const BYTE g_rgbPrime[] =
{
0x91, 0x02, 0xc8, 0x31, 0xee, 0x36, 0x07, 0xec,
0xc2, 0x24, 0x37, 0xf8, 0xfb, 0x3d, 0x69, 0x49,
0xac, 0x7a, 0xab, 0x32, 0xac, 0xad, 0xe9, 0xc2,
0xaf, 0x0e, 0x21, 0xb7, 0xc5, 0x2f, 0x76, 0xd0,
0xe5, 0x82, 0x78, 0x0d, 0x4f, 0x32, 0xb8, 0xcb,
0xf7, 0x0c, 0x8d, 0xfb, 0x3a, 0xd8, 0xc0, 0xea,
0xcb, 0x69, 0x68, 0xb0, 0x9b, 0x75, 0x25, 0x3d,
0xaa, 0x76, 0x22, 0x49, 0x94, 0xa4, 0xf2, 0x8d
};
// Generator in little-endian format.
static BYTE g_rgbGenerator[] =
{
0x02, 0x88, 0xd7, 0xe6, 0x53, 0xaf, 0x72, 0xc5,
0x8c, 0x08, 0x4b, 0x46, 0x6f, 0x9f, 0x2e, 0xc4,
0x9c, 0x5c, 0x92, 0x21, 0x95, 0xb7, 0xe5, 0x58,
0xbf, 0xba, 0x24, 0xfa, 0xe5, 0x9d, 0xcb, 0x71,
0x2e, 0x2c, 0xce, 0x99, 0xf3, 0x10, 0xff, 0x3b,
0xcb, 0xef, 0x6c, 0x95, 0x22, 0x55, 0x9d, 0x29,
0x00, 0xb5, 0x4c, 0x5b, 0xa5, 0x63, 0x31, 0x41,
0x13, 0x0a, 0xea, 0x39, 0x78, 0x02, 0x6d, 0x62
};
BYTE g_rgbData[] = {0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08};
int _tmain(int argc, _TCHAR* argv[])
{
UNREFERENCED_PARAMETER(argc);
UNREFERENCED_PARAMETER(argv);
BOOL fReturn;
HCRYPTPROV hProvParty1 = NULL;
HCRYPTPROV hProvParty2 = NULL;
DATA_BLOB P;
DATA_BLOB G;
HCRYPTKEY hPrivateKey1 = NULL;
HCRYPTKEY hPrivateKey2 = NULL;
PBYTE pbKeyBlob1 = NULL;
PBYTE pbKeyBlob2 = NULL;
HCRYPTKEY hSessionKey1 = NULL;
HCRYPTKEY hSessionKey2 = NULL;
PBYTE pbData = NULL;
/************************
Construct data BLOBs for the prime and generator. The P and G
values, represented by the g_rgbPrime and g_rgbGenerator arrays
respectively, are shared values that have been agreed to by both
parties.
************************/
P.cbData = DHKEYSIZE/8;
P.pbData = (BYTE*)(g_rgbPrime);
G.cbData = DHKEYSIZE/8;
G.pbData = (BYTE*)(g_rgbGenerator);
/************************
Create the private Diffie-Hellman key for party 1.
************************/
// Acquire a provider handle for party 1.
fReturn = CryptAcquireContext(
&hProvParty1,
NULL,
MS_ENH_DSS_DH_PROV,
PROV_DSS_DH,
CRYPT_VERIFYCONTEXT);
if(!fReturn)
{
goto ErrorExit;
}
// Create an ephemeral private key for party 1.
fReturn = CryptGenKey(
hProvParty1,
CALG_DH_EPHEM,
DHKEYSIZE << 16 | CRYPT_EXPORTABLE | CRYPT_PREGEN,
&hPrivateKey1);
if(!fReturn)
{
goto ErrorExit;
}
// Set the prime for party 1's private key.
fReturn = CryptSetKeyParam(
hPrivateKey1,
KP_P,
(PBYTE)&P,
0);
if(!fReturn)
{
goto ErrorExit;
}
// Set the generator for party 1's private key.
fReturn = CryptSetKeyParam(
hPrivateKey1,
KP_G,
(PBYTE)&G,
0);
if(!fReturn)
{
goto ErrorExit;
}
// Generate the secret values for party 1's private key.
fReturn = CryptSetKeyParam(
hPrivateKey1,
KP_X,
NULL,
0);
if(!fReturn)
{
goto ErrorExit;
}
/************************
Create the private Diffie-Hellman key for party 2.
************************/
// Acquire a provider handle for party 2.
fReturn = CryptAcquireContext(
&hProvParty2,
NULL,
MS_ENH_DSS_DH_PROV,
PROV_DSS_DH,
CRYPT_VERIFYCONTEXT);
if(!fReturn)
{
goto ErrorExit;
}
// Create an ephemeral private key for party 2.
fReturn = CryptGenKey(
hProvParty2,
CALG_DH_EPHEM,
DHKEYSIZE << 16 | CRYPT_EXPORTABLE | CRYPT_PREGEN,
&hPrivateKey2);
if(!fReturn)
{
goto ErrorExit;
}
// Set the prime for party 2's private key.
fReturn = CryptSetKeyParam(
hPrivateKey2,
KP_P,
(PBYTE)&P,
0);
if(!fReturn)
{
goto ErrorExit;
}
// Set the generator for party 2's private key.
fReturn = CryptSetKeyParam(
hPrivateKey2,
KP_G,
(PBYTE)&G,
0);
if(!fReturn)
{
goto ErrorExit;
}
// Generate the secret values for party 2's private key.
fReturn = CryptSetKeyParam(
hPrivateKey2,
KP_X,
NULL,
0);
if(!fReturn)
{
goto ErrorExit;
}
/************************
Export Party 1's public key.
************************/
// Public key value, (G^X) mod P is calculated.
DWORD dwDataLen1;
// Get the size for the key BLOB.
fReturn = CryptExportKey(
hPrivateKey1,
NULL,
PUBLICKEYBLOB,
0,
NULL,
&dwDataLen1);
if(!fReturn)
{
goto ErrorExit;
}
// Allocate the memory for the key BLOB.
if(!(pbKeyBlob1 = (PBYTE)malloc(dwDataLen1)))
{
goto ErrorExit;
}
// Get the key BLOB.
fReturn = CryptExportKey(
hPrivateKey1,
0,
PUBLICKEYBLOB,
0,
pbKeyBlob1,
&dwDataLen1);
if(!fReturn)
{
goto ErrorExit;
}
/************************
Export Party 2's public key.
************************/
// Public key value, (G^X) mod P is calculated.
DWORD dwDataLen2;
// Get the size for the key BLOB.
fReturn = CryptExportKey(
hPrivateKey2,
NULL,
PUBLICKEYBLOB,
0,
NULL,
&dwDataLen2);
if(!fReturn)
{
goto ErrorExit;
}
// Allocate the memory for the key BLOB.
if(!(pbKeyBlob2 = (PBYTE)malloc(dwDataLen2)))
{
goto ErrorExit;
}
// Get the key BLOB.
fReturn = CryptExportKey(
hPrivateKey2,
0,
PUBLICKEYBLOB,
0,
pbKeyBlob2,
&dwDataLen2);
if(!fReturn)
{
goto ErrorExit;
}
/************************
Party 1 imports party 2's public key.
The imported key will contain the new shared secret
key (Y^X) mod P.
************************/
fReturn = CryptImportKey(
hProvParty1,
pbKeyBlob2,
dwDataLen2,
hPrivateKey1,
0,
&hSessionKey2);
if(!fReturn)
{
goto ErrorExit;
}
/************************
Party 2 imports party 1's public key.
The imported key will contain the new shared secret
key (Y^X) mod P.
************************/
fReturn = CryptImportKey(
hProvParty2,
pbKeyBlob1,
dwDataLen1,
hPrivateKey2,
0,
&hSessionKey1);
if(!fReturn)
{
goto ErrorExit;
}
/************************
Convert the agreed keys to symmetric keys. They are currently of
the form CALG_AGREEDKEY_ANY. Convert them to CALG_RC4.
************************/
ALG_ID Algid = CALG_RC4;
// Enable the party 1 public session key for use by setting the
// ALGID.
fReturn = CryptSetKeyParam(
hSessionKey1,
KP_ALGID,
(PBYTE)&Algid,
0);
if(!fReturn)
{
goto ErrorExit;
}
// Enable the party 2 public session key for use by setting the
// ALGID.
fReturn = CryptSetKeyParam(
hSessionKey2,
KP_ALGID,
(PBYTE)&Algid,
0);
if(!fReturn)
{
goto ErrorExit;
}
/************************
Encrypt some data with party 1's session key.
************************/
// Get the size.
DWORD dwLength = sizeof(g_rgbData);
fReturn = CryptEncrypt(
hSessionKey1,
0,
TRUE,
0,
NULL,
&dwLength,
sizeof(g_rgbData));
if(!fReturn)
{
goto ErrorExit;
}
// Allocate a buffer to hold the encrypted data.
pbData = (PBYTE)malloc(dwLength);
if(!pbData)
{
goto ErrorExit;
}
// Copy the unencrypted data to the buffer. The data will be
// encrypted in place.
memcpy(pbData, g_rgbData, sizeof(g_rgbData));
// Encrypt the data.
dwLength = sizeof(g_rgbData);
fReturn = CryptEncrypt(
hSessionKey1,
0,
TRUE,
0,
pbData,
&dwLength,
sizeof(g_rgbData));
if(!fReturn)
{
goto ErrorExit;
}
/************************
Decrypt the data with party 2's session key.
************************/
dwLength = sizeof(g_rgbData);
fReturn = CryptDecrypt(
hSessionKey2,
0,
TRUE,
0,
pbData,
&dwLength);
if(!fReturn)
{
goto ErrorExit;
}
ErrorExit:
if(pbData)
{
free(pbData);
pbData = NULL;
}
if(hSessionKey2)
{
CryptDestroyKey(hSessionKey2);
hSessionKey2 = NULL;
}
if(hSessionKey1)
{
CryptDestroyKey(hSessionKey1);
hSessionKey1 = NULL;
}
if(pbKeyBlob2)
{
free(pbKeyBlob2);
pbKeyBlob2 = NULL;
}
if(pbKeyBlob1)
{
free(pbKeyBlob1);
pbKeyBlob1 = NULL;
}
if(hPrivateKey2)
{
CryptDestroyKey(hPrivateKey2);
hPrivateKey2 = NULL;
}
if(hPrivateKey1)
{
CryptDestroyKey(hPrivateKey1);
hPrivateKey1 = NULL;
}
if(hProvParty2)
{
CryptReleaseContext(hProvParty2, 0);
hProvParty2 = NULL;
}
if(hProvParty1)
{
CryptReleaseContext(hProvParty1, 0);
hProvParty1 = NULL;
}
return 0;
}
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for