diff options
Diffstat (limited to 'src/include/openssl/dh.h')
| -rw-r--r-- | src/include/openssl/dh.h | 184 |
1 files changed, 87 insertions, 97 deletions
diff --git a/src/include/openssl/dh.h b/src/include/openssl/dh.h index 9f92a062..d78bbeba 100644 --- a/src/include/openssl/dh.h +++ b/src/include/openssl/dh.h @@ -59,7 +59,6 @@ #include <openssl/base.h> -#include <openssl/engine.h> #include <openssl/ex_data.h> #include <openssl/thread.h> @@ -68,92 +67,83 @@ extern "C" { #endif -/* DH contains functions for performing Diffie-Hellman key agreement in - * multiplicative groups. */ +// DH contains functions for performing Diffie-Hellman key agreement in +// multiplicative groups. -/* Allocation and destruction. */ +// Allocation and destruction. -/* DH_new returns a new, empty DH object or NULL on error. */ +// DH_new returns a new, empty DH object or NULL on error. OPENSSL_EXPORT DH *DH_new(void); -/* DH_free decrements the reference count of |dh| and frees it if the reference - * count drops to zero. */ +// DH_free decrements the reference count of |dh| and frees it if the reference +// count drops to zero. OPENSSL_EXPORT void DH_free(DH *dh); -/* DH_up_ref increments the reference count of |dh| and returns one. */ +// DH_up_ref increments the reference count of |dh| and returns one. OPENSSL_EXPORT int DH_up_ref(DH *dh); -/* Properties. */ +// Properties. -/* DH_get0_key sets |*out_pub_key| and |*out_priv_key|, if non-NULL, to |dh|'s - * public and private key, respectively. If |dh| is a public key, the private - * key will be set to NULL. */ +// DH_get0_key sets |*out_pub_key| and |*out_priv_key|, if non-NULL, to |dh|'s +// public and private key, respectively. If |dh| is a public key, the private +// key will be set to NULL. OPENSSL_EXPORT void DH_get0_key(const DH *dh, const BIGNUM **out_pub_key, const BIGNUM **out_priv_key); -/* DH_get0_pqg sets |*out_p|, |*out_q|, and |*out_g|, if non-NULL, to |dh|'s p, - * q, and g parameters, respectively. */ +// DH_get0_pqg sets |*out_p|, |*out_q|, and |*out_g|, if non-NULL, to |dh|'s p, +// q, and g parameters, respectively. OPENSSL_EXPORT void DH_get0_pqg(const DH *dh, const BIGNUM **out_p, const BIGNUM **out_q, const BIGNUM **out_g); -/* Standard parameters. - * - * These functions return new DH objects with standard parameters. They return - * NULL on allocation failure. The |engine| parameter is ignored. */ - -/* These parameters are taken from RFC 5114. */ +// Standard parameters. -OPENSSL_EXPORT DH *DH_get_1024_160(const ENGINE *engine); -OPENSSL_EXPORT DH *DH_get_2048_224(const ENGINE *engine); -OPENSSL_EXPORT DH *DH_get_2048_256(const ENGINE *engine); - -/* BN_get_rfc3526_prime_1536 sets |*ret| to the 1536-bit MODP group from RFC - * 3526 and returns |ret|. If |ret| is NULL then a fresh |BIGNUM| is allocated - * and returned. It returns NULL on allocation failure. */ +// BN_get_rfc3526_prime_1536 sets |*ret| to the 1536-bit MODP group from RFC +// 3526 and returns |ret|. If |ret| is NULL then a fresh |BIGNUM| is allocated +// and returned. It returns NULL on allocation failure. OPENSSL_EXPORT BIGNUM *BN_get_rfc3526_prime_1536(BIGNUM *ret); -/* Parameter generation. */ +// Parameter generation. #define DH_GENERATOR_2 2 #define DH_GENERATOR_5 5 -/* DH_generate_parameters_ex generates a suitable Diffie-Hellman group with a - * prime that is |prime_bits| long and stores it in |dh|. The generator of the - * group will be |generator|, which should be |DH_GENERATOR_2| unless there's a - * good reason to use a different value. The |cb| argument contains a callback - * function that will be called during the generation. See the documentation in - * |bn.h| about this. In addition to the callback invocations from |BN|, |cb| - * will also be called with |event| equal to three when the generation is - * complete. */ +// DH_generate_parameters_ex generates a suitable Diffie-Hellman group with a +// prime that is |prime_bits| long and stores it in |dh|. The generator of the +// group will be |generator|, which should be |DH_GENERATOR_2| unless there's a +// good reason to use a different value. The |cb| argument contains a callback +// function that will be called during the generation. See the documentation in +// |bn.h| about this. In addition to the callback invocations from |BN|, |cb| +// will also be called with |event| equal to three when the generation is +// complete. OPENSSL_EXPORT int DH_generate_parameters_ex(DH *dh, int prime_bits, int generator, BN_GENCB *cb); -/* Diffie-Hellman operations. */ +// Diffie-Hellman operations. -/* DH_generate_key generates a new, random, private key and stores it in - * |dh|. It returns one on success and zero on error. */ +// DH_generate_key generates a new, random, private key and stores it in +// |dh|. It returns one on success and zero on error. OPENSSL_EXPORT int DH_generate_key(DH *dh); -/* DH_compute_key calculates the shared key between |dh| and |peers_key| and - * writes it as a big-endian integer into |out|, which must have |DH_size| - * bytes of space. It returns the number of bytes written, or a negative number - * on error. */ +// DH_compute_key calculates the shared key between |dh| and |peers_key| and +// writes it as a big-endian integer into |out|, which must have |DH_size| +// bytes of space. It returns the number of bytes written, or a negative number +// on error. OPENSSL_EXPORT int DH_compute_key(uint8_t *out, const BIGNUM *peers_key, DH *dh); -/* Utility functions. */ +// Utility functions. -/* DH_size returns the number of bytes in the DH group's prime. */ +// DH_size returns the number of bytes in the DH group's prime. OPENSSL_EXPORT int DH_size(const DH *dh); -/* DH_num_bits returns the minimum number of bits needed to represent the - * absolute value of the DH group's prime. */ +// DH_num_bits returns the minimum number of bits needed to represent the +// absolute value of the DH group's prime. OPENSSL_EXPORT unsigned DH_num_bits(const DH *dh); #define DH_CHECK_P_NOT_PRIME 0x01 @@ -164,49 +154,49 @@ OPENSSL_EXPORT unsigned DH_num_bits(const DH *dh); #define DH_CHECK_INVALID_Q_VALUE 0x20 #define DH_CHECK_INVALID_J_VALUE 0x40 -/* These are compatibility defines. */ +// These are compatibility defines. #define DH_NOT_SUITABLE_GENERATOR DH_CHECK_NOT_SUITABLE_GENERATOR #define DH_UNABLE_TO_CHECK_GENERATOR DH_CHECK_UNABLE_TO_CHECK_GENERATOR -/* DH_check checks the suitability of |dh| as a Diffie-Hellman group. and sets - * |DH_CHECK_*| flags in |*out_flags| if it finds any errors. It returns one if - * |*out_flags| was successfully set and zero on error. - * - * Note: these checks may be quite computationally expensive. */ +// DH_check checks the suitability of |dh| as a Diffie-Hellman group. and sets +// |DH_CHECK_*| flags in |*out_flags| if it finds any errors. It returns one if +// |*out_flags| was successfully set and zero on error. +// +// Note: these checks may be quite computationally expensive. OPENSSL_EXPORT int DH_check(const DH *dh, int *out_flags); #define DH_CHECK_PUBKEY_TOO_SMALL 0x1 #define DH_CHECK_PUBKEY_TOO_LARGE 0x2 #define DH_CHECK_PUBKEY_INVALID 0x4 -/* DH_check_pub_key checks the suitability of |pub_key| as a public key for the - * DH group in |dh| and sets |DH_CHECK_PUBKEY_*| flags in |*out_flags| if it - * finds any errors. It returns one if |*out_flags| was successfully set and - * zero on error. */ +// DH_check_pub_key checks the suitability of |pub_key| as a public key for the +// DH group in |dh| and sets |DH_CHECK_PUBKEY_*| flags in |*out_flags| if it +// finds any errors. It returns one if |*out_flags| was successfully set and +// zero on error. OPENSSL_EXPORT int DH_check_pub_key(const DH *dh, const BIGNUM *pub_key, int *out_flags); -/* DHparams_dup allocates a fresh |DH| and copies the parameters from |dh| into - * it. It returns the new |DH| or NULL on error. */ +// DHparams_dup allocates a fresh |DH| and copies the parameters from |dh| into +// it. It returns the new |DH| or NULL on error. OPENSSL_EXPORT DH *DHparams_dup(const DH *dh); -/* ASN.1 functions. */ +// ASN.1 functions. -/* DH_parse_parameters decodes a DER-encoded DHParameter structure (PKCS #3) - * from |cbs| and advances |cbs|. It returns a newly-allocated |DH| or NULL on - * error. */ +// DH_parse_parameters decodes a DER-encoded DHParameter structure (PKCS #3) +// from |cbs| and advances |cbs|. It returns a newly-allocated |DH| or NULL on +// error. OPENSSL_EXPORT DH *DH_parse_parameters(CBS *cbs); -/* DH_marshal_parameters marshals |dh| as a DER-encoded DHParameter structure - * (PKCS #3) and appends the result to |cbb|. It returns one on success and zero - * on error. */ +// DH_marshal_parameters marshals |dh| as a DER-encoded DHParameter structure +// (PKCS #3) and appends the result to |cbb|. It returns one on success and zero +// on error. OPENSSL_EXPORT int DH_marshal_parameters(CBB *cbb, const DH *dh); -/* ex_data functions. - * - * See |ex_data.h| for details. */ +// ex_data functions. +// +// See |ex_data.h| for details. OPENSSL_EXPORT int DH_get_ex_new_index(long argl, void *argp, CRYPTO_EX_unused *unused, @@ -216,50 +206,50 @@ OPENSSL_EXPORT int DH_set_ex_data(DH *d, int idx, void *arg); OPENSSL_EXPORT void *DH_get_ex_data(DH *d, int idx); -/* Deprecated functions. */ +// Deprecated functions. -/* DH_generate_parameters behaves like |DH_generate_parameters_ex|, which is - * what you should use instead. It returns NULL on error, or a newly-allocated - * |DH| on success. This function is provided for compatibility only. */ +// DH_generate_parameters behaves like |DH_generate_parameters_ex|, which is +// what you should use instead. It returns NULL on error, or a newly-allocated +// |DH| on success. This function is provided for compatibility only. OPENSSL_EXPORT DH *DH_generate_parameters(int prime_len, int generator, void (*callback)(int, int, void *), void *cb_arg); -/* d2i_DHparams parses an ASN.1, DER encoded Diffie-Hellman parameters structure - * from |len| bytes at |*inp|. If |ret| is not NULL then, on exit, a pointer to - * the result is in |*ret|. Note that, even if |*ret| is already non-NULL on - * entry, it will not be written to. Rather, a fresh |DH| is allocated and the - * previous one is freed. - * - * On successful exit, |*inp| is advanced past the DER structure. It - * returns the result or NULL on error. - * - * Use |DH_parse_parameters| instead. */ +// d2i_DHparams parses an ASN.1, DER encoded Diffie-Hellman parameters structure +// from |len| bytes at |*inp|. If |ret| is not NULL then, on exit, a pointer to +// the result is in |*ret|. Note that, even if |*ret| is already non-NULL on +// entry, it will not be written to. Rather, a fresh |DH| is allocated and the +// previous one is freed. +// +// On successful exit, |*inp| is advanced past the DER structure. It +// returns the result or NULL on error. +// +// Use |DH_parse_parameters| instead. OPENSSL_EXPORT DH *d2i_DHparams(DH **ret, const unsigned char **inp, long len); -/* i2d_DHparams marshals |in| to an ASN.1, DER structure. If |outp| is not NULL - * then the result is written to |*outp| and |*outp| is advanced just past the - * output. It returns the number of bytes in the result, whether written or - * not, or a negative value on error. - * - * Use |DH_marshal_parameters| instead. */ +// i2d_DHparams marshals |in| to an ASN.1, DER structure. If |outp| is not NULL +// then the result is written to |*outp| and |*outp| is advanced just past the +// output. It returns the number of bytes in the result, whether written or +// not, or a negative value on error. +// +// Use |DH_marshal_parameters| instead. OPENSSL_EXPORT int i2d_DHparams(const DH *in, unsigned char **outp); struct dh_st { BIGNUM *p; BIGNUM *g; - BIGNUM *pub_key; /* g^x mod p */ - BIGNUM *priv_key; /* x */ + BIGNUM *pub_key; // g^x mod p + BIGNUM *priv_key; // x - /* priv_length contains the length, in bits, of the private value. If zero, - * the private value will be the same length as |p|. */ + // priv_length contains the length, in bits, of the private value. If zero, + // the private value will be the same length as |p|. unsigned priv_length; CRYPTO_MUTEX method_mont_p_lock; BN_MONT_CTX *method_mont_p; - /* Place holders if we want to do X9.42 DH */ + // Place holders if we want to do X9.42 DH BIGNUM *q; BIGNUM *j; unsigned char *seed; @@ -273,7 +263,7 @@ struct dh_st { #if defined(__cplusplus) -} /* extern C */ +} // extern C extern "C++" { @@ -283,7 +273,7 @@ BORINGSSL_MAKE_DELETER(DH, DH_free) } // namespace bssl -} /* extern C++ */ +} // extern C++ #endif @@ -294,4 +284,4 @@ BORINGSSL_MAKE_DELETER(DH, DH_free) #define DH_R_DECODE_ERROR 104 #define DH_R_ENCODE_ERROR 105 -#endif /* OPENSSL_HEADER_DH_H */ +#endif // OPENSSL_HEADER_DH_H |