Dh C Library Reference
Dh
Diffie-Hellman key-exchange C library.
Diffie-Hellman (D-H) key exchange is a cryptographic protocol that allows two parties that have no prior knowledge of each other to jointly establish a shared secret key over an insecure communications channel. This key can then be used to encrypt subsequent communications using a symmetric key cipher.
Synonyms of Diffie-Hellman key exchange include:
- Diffie-Hellman key agreement
- Diffie-Hellman key establishment
- Diffie-Hellman key negotiation
- exponential key exchange
Create/Dispose
HCkDh CkDh_Create(void);
Creates an instance of the CkDh object and returns a handle (i.e. a "void *" pointer). The handle is passed in the 1st argument for the functions listed on this page.
void CkDh_Dispose(HCkDh handle);
Objects created by calling CkDh_Create must be freed by calling this method. A memory leak occurs if a handle is not disposed by calling this function.
C "Properties"
int CkDh_getG(HCkDh cHandle);
The generator. The value of G should be either 2 or 5.
void CkDh_getLastErrorHtml(HCkDh cHandle, HCkString retval);
Error information in HTML format for the last method called.
void CkDh_getLastErrorText(HCkDh cHandle, HCkString retval);
Error information in plain-text format for the last method called.
void CkDh_getLastErrorXml(HCkDh cHandle, HCkString retval);
Error information in XML format for the last method called.
void CPP_CLASS_getP(HCkDh cHandle, HCkString retval);
A "safe" large prime returned as a hex string. The hex string represent a bignum in SSH1 format.
BOOL CkDh_getUtf8(HCkDh cHandle);
void CkDh_putUtf8(HCkDh cHandle, BOOL newVal);
To be documented soon...
void CkDh_getVersion(HCkDh cHandle, HCkString retval);
A version string, such as "1.2.0"
C "Methods"
BOOL CkDh_CreateE(HCkDh cHandle, int numBits, HCkString outStr);
The 1st step in Diffie-Hellman key exchange (to generate a shared-secret). The numBits should be twice the size (in bits) of the shared secret to be generated. For example, if you are using DH to create a 128-bit AES session key, then numBits should be set to 256. Returns E as a bignum in SSH-format as a hex string.
BOOL CkDh_FindK(HCkDh cHandle, const char *e, HCkString outStr);
The 2nd and final step in Diffie-Hellman (DH) key exchange. E is the E created by the other party. Returns the shared secret (K) as an SSH1-format bignum encoded as a hex string.
BOOL CkDh_GenPG(HCkDh cHandle, int numBits, int g);
Generates a large safe prime that is numBits bits in size using the generator G. Generating a new (random) P is expensive in both time and CPU cycles. A prime should be 1024 or more bits in length.
BOOL CkDh_SaveLastError(HCkDh cHandle, const char *filename);
Saves the last error information to an XML formatted file.
BOOL CkDh_SetPG(HCkDh cHandle, const char *p, int g);
Sets explicit values for P and G. Returns true if P and G conform to the requirements for Diffie-Hellman. P is an SSH1-format bignum passed as a hexidecimalized string.
BOOL CkDh_UnlockComponent(HCkDh cHandle, const char *unlockCode);
To be documented soon...
void CkDh_UseKnownPrime(HCkDh cHandle, int index);
Sets P and G to a known safe prime. The index may have the following values:
1: First Oakley Default Group from RFC2409, section 6.1. Generator is 2. The prime is: 2^768 - 2 ^704 - 1 + 2^64 * { [2^638 pi] + 149686 }
2: Prime for 2nd Oakley Group (RFC 2409) -- 1024-bit MODP Group. Generator is 2. The prime is: 2^1024 - 2^960 - 1 + 2^64 * { [2^894 pi] + 129093 }.
3: 1536-bit MODP Group from RFC3526, Section 2. Generator is 2. The prime is: 2^1536 - 2^1472 - 1 + 2^64 * { [2^1406 pi] + 741804 }
4: Prime for 14th Oakley Group (RFC 3526) -- 2048-bit MODP Group. Generator is 2. The prime is: 2^2048 - 2^1984 - 1 + 2^64 * { [2^1918 pi] + 124476 }
5: 3072-bit MODP Group from RFC3526, Section 4. Generator is 2. The prime is: 2^3072 - 2^3008 - 1 + 2^64 * { [2^2942 pi] + 1690314 }
6: 4096-bit MODP Group from RFC3526, Section 5. Generator is 2. The prime is: 2^4096 - 2^4032 - 1 + 2^64 * { [2^3966 pi] + 240904 }
7: 6144-bit MODP Group from RFC3526, Section 6. Generator is 2. The prime is: 2^6144 - 2^6080 - 1 + 2^64 * { [2^6014 pi] + 929484 }
8: 8192-bit MODP Group from RFC3526, Section 7. Generator is 2. The prime is: 2^8192 - 2^8128 - 1 + 2^64 * { [2^8062 pi] + 4743158 }
const char *CkDh_createE(HCkDh cHandle, int numBits);
The 1st step in Diffie-Hellman key exchange (to generate a shared-secret). The numBits should be twice the size (in bits) of the shared secret to be generated. For example, if you are using DH to create a 128-bit AES session key, then numBits should be set to 256. Returns E as a bignum in SSH-format as a hex string. Returns a null on failure
const char *CkDh_findK(HCkDh cHandle, const char *e);
The 2nd and final step in Diffie-Hellman (DH) key exchange. E is the E created by the other party. Returns the shared secret (K) as an SSH1-format bignum encoded as a hex string. Returns a null on failure
const char *CkDh_lastErrorHtml(HCkDh cHandle);
Error information in HTML format for the last method called.Returns a null on failure
const char *CkDh_lastErrorText(HCkDh cHandle);
Error information in plain-text format for the last method called.Returns a null on failure
const char *CkDh_lastErrorXml(HCkDh cHandle);
Error information in XML format for the last method called.Returns a null on failure
const char *CkDh_p(HCkDh cHandle);
A "safe" large prime returned as a hex string. The hex string represent a bignum in SSH1 format. Returns a null on failure
const char *CkDh_version(HCkDh cHandle);
A version string, such as "1.2.0" Returns a null on failure
|