Diffie-Hellman (DH)
[Discrete Logarithm Cryptography (DLC)]

Diffie-Hellman shared secret computation in discrete logarithm (DL) domain. More...

Functions

C4eArchSize c4e_dlc_dh_std (C4eDlcDomain *C4E_RESTRICT dom, C4E_CONST C4eElement *C4E_RESTRICT d, C4eArchDigit tmp[C4E_RESTRICT], C4eElement *C4E_RESTRICT e, C4eArchUint8 *C4E_RESTRICT secret)
 "Standard" Diffie-Hellman shared secret computation in DL domain (according to PKCS #3, IEEE Std 1363, ANSI X9.42, ISO 11770-3, NIST SP800-56A, RFC 2631, etc).
C4eArchSize c4e_dlc_dh_tls (C4eDlcDomain *C4E_RESTRICT dom, C4E_CONST C4eElement *C4E_RESTRICT d, C4eArchDigit tmp[C4E_RESTRICT], C4eElement *C4E_RESTRICT e, C4eArchUint8 *C4E_RESTRICT secret)
 Diffie-Hellman shared secret computation according to SSL/TLS.

Detailed Description

Diffie-Hellman shared secret computation in discrete logarithm (DL) domain.

Function Documentation

C4eArchSize c4e_dlc_dh_std ( C4eDlcDomain *C4E_RESTRICT  dom,
C4E_CONST C4eElement *C4E_RESTRICT  d,
C4eArchDigit  tmp[C4E_RESTRICT],
C4eElement *C4E_RESTRICT  e,
C4eArchUint8 *C4E_RESTRICT  secret 
)

"Standard" Diffie-Hellman shared secret computation in DL domain (according to PKCS #3, IEEE Std 1363, ANSI X9.42, ISO 11770-3, NIST SP800-56A, RFC 2631, etc).

This function performes an exponentiation of e by the private exponent d modulo dom->m, resulting in a shared secret $ z=e^d \bmod m $ .

Note:
This function does not perform any key derivation, as for example specified by:
  • IEEE Std 1363, section 9.2.1 (DLKAS-DH1);
  • ANSI X9.42, section 7.7 (Key Derivation from Shared Secret Value);
  • ANSI X9.63, section 5.6.3 (Key Derivation Functions);
  • NIST SP800-56A, section 5.8 (Key-Derivation Methods for Key-Agreement Schemes);
  • RFC 2631, section 2.1.2 (Generation of Keying Material);
  • BSI TR-03111, section 4.3.3 (Key Derivation Functions).

It simply calculates the shared secret, which is the starting point for deriving a shared (symmetric) session key.

Attention:
The domain parameter dom->m.val is temporary modified - so it must be writable. After function return it holds the same values as at function entry.
Precondition:
The validity of the DL domain parameters in dom must be assured by the caller, either implicit or by using function c4e_dlc_domchk().
The validity of the private DH key d must be assured by the caller, either implicit or by using function c4e_dlc_keychk_prv().
The validity of the public DH key e must be assured by the caller, for example by using function c4e_dlc_keychk_pub().
The required digits space (in units of C4eArchDigit) for public key e is (dom->m.val.size + 1).
The caller must provide temporary memory space in array tmp[], using macro C4E_DLC_TMP_NUM() in conjunction with temp. space qualifier C4E_DLC_DH_TMPID_STD.
Bibliography:
PKCS #3: Diffie-Hellman Key-Agreement Standard. 1993.
Bibliography:
E. Rescorla: Diffie-Hellman Key Agreement Method. RFC 2631, IETF, June 1999.
Bibliography:
Standard Specifications For Public-Key Cryptography. Std 1363-2000, IEEE, 2000.
Bibliography:
Public Key Cryptography for the Financial Services Industry: Agreement of Symmetric Keys Using Discrete Logarithm Cryptography. ANSI X9.42, 2003.
Bibliography:
Information technology - Security techniques - Key management - Part 3: Mechanisms using asymmetric techniques. ISO 11770-3, 2008.
Parameters:
[in] dom Pointer to DLC domain parameters.
[in] d Pointer to DH private key.
tmp Array of temporary space elements (see preconditions for details on size).
[in] e Other party DH public key (from DL domain). Notice that public key e is destroyed.
[out] secret Shared secret of both parties, in network byte order.
Returns:
The length of shared secret, which is dom->m.len on success. Any other value should be interpreted as error.
See also:
c4e_dlc_keychk_prv(), c4e_dlc_keychk_pub(), c4e_dlc_domchk(), c4e_dlc_dh_tls(), C4E_DLC_DH_TMPID_STD
C4eArchSize c4e_dlc_dh_tls ( C4eDlcDomain *C4E_RESTRICT  dom,
C4E_CONST C4eElement *C4E_RESTRICT  d,
C4eArchDigit  tmp[C4E_RESTRICT],
C4eElement *C4E_RESTRICT  e,
C4eArchUint8 *C4E_RESTRICT  secret 
)

Diffie-Hellman shared secret computation according to SSL/TLS.

Note:
This function does not perform any key derivation, as for example specified by:
  • IEEE Std 1363, section 9.2.1 (DLKAS-DH1);
  • ANSI X9.42, section 7.7 (Key Derivation from Shared Secret Value);
  • ANSI X9.63, section 5.6.3 (Key Derivation Functions);
  • NIST SP800-56A, section 5.8 (Key-Derivation Methods for Key-Agreement Schemes);
  • RFC 2631, section 2.1.2 (Generation of Keying Material);
  • BSI TR-03111, section 4.3.3 (Key Derivation Functions).

It simply calculates the shared secret (with leading zeros stripped), which is the starting point for deriving a shared (symmetric) session key.

Notice that this DH implementation (also the implementation of OpenSSL) is compliant with the SSL/TLS requirement from RFC 5246, section 8.1.2, that leading zeroes on the shared secret must be stripped. For example PKCS #3 does not specify such a requirement. Standards like ANSI X9.42 (RFC 2631) and IEEE Std 1363 apply a hash function combined with some other stuff after computing the shared secret - so it makes no sense for these standards to strip leading zeros.

Attention:
The domain parameter dom->m.val is temporary modified - so it must be writable. After function return it holds the same values as at function entry.
Precondition:
The validity of the DL domain parameters in dom must be assured by the caller, either implicit or by using function c4e_dlc_domchk().
The validity of the private DH key d must be assured by the caller, either implicit or by using function c4e_dlc_keychk_prv().
The validity of the public DH key must be assured by the caller, for example by using function c4e_dlc_keychk_pub().
The required digits space (in units of C4eArchDigit) for public key e is (dom->m.val.size + 1).
The caller must provide temporary memory space in array tmp[], using macro C4E_DLC_TMP_NUM() in conjunction with temp. space qualifier C4E_DLC_DH_TMPID_TLS.
Bibliography:
Dierks, T. and E. Rescorla: The Transport Layer Security (TLS) Protocol Version 1.2. RFC 5246, IETF, August 2008.
Parameters:
[in] dom Pointer to DLC domain parameters.
[in] d Pointer to DH private key.
tmp Array of temporary space elements (see preconditions for details on size).
[in] e Other party DH public key (from DL domain). Notice that public key e is destroyed.
[out] secret Shared secret of both parties, in network byte order (leading zeros stripped).
Returns:
The length of shared secret (less/equal than dom->m.len), 0 on error.
See also:
c4e_dlc_keychk_prv(), c4e_dlc_keychk_pub(), c4e_dlc_domchk(), c4e_dlc_dh_std(), C4E_DLC_DH_TMPID_TLS, C4E_ELEM_ASGN_MEM()
Generated by Ralf Hoppe, Ginsterweg 49, 73230 Kirchheim unter Teck, Germany
on Sun Jun 7 14:10:51 2015 for CRY4E using doxygen 1.6.1