1 /* 2 * Copyright 1995-2016 The OpenSSL Project Authors. All Rights Reserved. 3 * 4 * Licensed under the OpenSSL license (the "License"). You may not use 5 * this file except in compliance with the License. You can obtain a copy 6 * in the file LICENSE in the source distribution or at 7 * https://www.openssl.org/source/license.html 8 */ 9 10 #ifndef OPENSSL_HEADER_DH_H 11 #define OPENSSL_HEADER_DH_H 12 13 #include <openssl/base.h> 14 15 #include <openssl/thread.h> 16 17 #if defined(__cplusplus) 18 extern "C" { 19 #endif 20 21 22 // DH contains functions for performing Diffie-Hellman key agreement in 23 // multiplicative groups. 24 // 25 // This module is deprecated and retained for legacy reasons only. It is not 26 // considered a priority for performance or hardening work. Do not use it in 27 // new code. Use X25519 or ECDH with P-256 instead. 28 29 30 // Allocation and destruction. 31 // 32 // A |DH| object represents a Diffie-Hellman key or group parameters. A given 33 // object may be used concurrently on multiple threads by non-mutating 34 // functions, provided no other thread is concurrently calling a mutating 35 // function. Unless otherwise documented, functions which take a |const| pointer 36 // are non-mutating and functions which take a non-|const| pointer are mutating. 37 38 // DH_new returns a new, empty DH object or NULL on error. 39 OPENSSL_EXPORT DH *DH_new(void); 40 41 // DH_free decrements the reference count of |dh| and frees it if the reference 42 // count drops to zero. 43 OPENSSL_EXPORT void DH_free(DH *dh); 44 45 // DH_up_ref increments the reference count of |dh| and returns one. It does not 46 // mutate |dh| for thread-safety purposes and may be used concurrently. 47 OPENSSL_EXPORT int DH_up_ref(DH *dh); 48 49 50 // Properties. 51 52 // OPENSSL_DH_MAX_MODULUS_BITS is the maximum supported Diffie-Hellman group 53 // modulus, in bits. 54 #define OPENSSL_DH_MAX_MODULUS_BITS 10000 55 56 // DH_bits returns the size of |dh|'s group modulus, in bits. 57 OPENSSL_EXPORT unsigned DH_bits(const DH *dh); 58 59 // DH_get0_pub_key returns |dh|'s public key. 60 OPENSSL_EXPORT const BIGNUM *DH_get0_pub_key(const DH *dh); 61 62 // DH_get0_priv_key returns |dh|'s private key, or NULL if |dh| is a public key. 63 OPENSSL_EXPORT const BIGNUM *DH_get0_priv_key(const DH *dh); 64 65 // DH_get0_p returns |dh|'s group modulus. 66 OPENSSL_EXPORT const BIGNUM *DH_get0_p(const DH *dh); 67 68 // DH_get0_q returns the size of |dh|'s subgroup, or NULL if it is unset. 69 OPENSSL_EXPORT const BIGNUM *DH_get0_q(const DH *dh); 70 71 // DH_get0_g returns |dh|'s group generator. 72 OPENSSL_EXPORT const BIGNUM *DH_get0_g(const DH *dh); 73 74 // DH_get0_key sets |*out_pub_key| and |*out_priv_key|, if non-NULL, to |dh|'s 75 // public and private key, respectively. If |dh| is a public key, the private 76 // key will be set to NULL. 77 OPENSSL_EXPORT void DH_get0_key(const DH *dh, const BIGNUM **out_pub_key, 78 const BIGNUM **out_priv_key); 79 80 // DH_set0_key sets |dh|'s public and private key to the specified values. If 81 // NULL, the field is left unchanged. On success, it takes ownership of each 82 // argument and returns one. Otherwise, it returns zero. 83 OPENSSL_EXPORT int DH_set0_key(DH *dh, BIGNUM *pub_key, BIGNUM *priv_key); 84 85 // DH_get0_pqg sets |*out_p|, |*out_q|, and |*out_g|, if non-NULL, to |dh|'s p, 86 // q, and g parameters, respectively. 87 OPENSSL_EXPORT void DH_get0_pqg(const DH *dh, const BIGNUM **out_p, 88 const BIGNUM **out_q, const BIGNUM **out_g); 89 90 // DH_set0_pqg sets |dh|'s p, q, and g parameters to the specified values. If 91 // NULL, the field is left unchanged. On success, it takes ownership of each 92 // argument and returns one. Otherwise, it returns zero. |q| may be NULL, but 93 // |p| and |g| must either be specified or already configured on |dh|. 94 OPENSSL_EXPORT int DH_set0_pqg(DH *dh, BIGNUM *p, BIGNUM *q, BIGNUM *g); 95 96 // DH_set_length sets the number of bits to use for the secret exponent when 97 // calling |DH_generate_key| on |dh| and returns one. If unset, 98 // |DH_generate_key| will use the bit length of p. 99 OPENSSL_EXPORT int DH_set_length(DH *dh, unsigned priv_length); 100 101 102 // Standard parameters. 103 104 // DH_get_rfc7919_2048 returns the group `ffdhe2048` from 105 // https://tools.ietf.org/html/rfc7919#appendix-A.1. It returns NULL if out 106 // of memory. 107 OPENSSL_EXPORT DH *DH_get_rfc7919_2048(void); 108 109 // BN_get_rfc3526_prime_1536 sets |*ret| to the 1536-bit MODP group from RFC 110 // 3526 and returns |ret|. If |ret| is NULL then a fresh |BIGNUM| is allocated 111 // and returned. It returns NULL on allocation failure. 112 OPENSSL_EXPORT BIGNUM *BN_get_rfc3526_prime_1536(BIGNUM *ret); 113 114 // BN_get_rfc3526_prime_2048 sets |*ret| to the 2048-bit MODP group from RFC 115 // 3526 and returns |ret|. If |ret| is NULL then a fresh |BIGNUM| is allocated 116 // and returned. It returns NULL on allocation failure. 117 OPENSSL_EXPORT BIGNUM *BN_get_rfc3526_prime_2048(BIGNUM *ret); 118 119 // BN_get_rfc3526_prime_3072 sets |*ret| to the 3072-bit MODP group from RFC 120 // 3526 and returns |ret|. If |ret| is NULL then a fresh |BIGNUM| is allocated 121 // and returned. It returns NULL on allocation failure. 122 OPENSSL_EXPORT BIGNUM *BN_get_rfc3526_prime_3072(BIGNUM *ret); 123 124 // BN_get_rfc3526_prime_4096 sets |*ret| to the 4096-bit MODP group from RFC 125 // 3526 and returns |ret|. If |ret| is NULL then a fresh |BIGNUM| is allocated 126 // and returned. It returns NULL on allocation failure. 127 OPENSSL_EXPORT BIGNUM *BN_get_rfc3526_prime_4096(BIGNUM *ret); 128 129 // BN_get_rfc3526_prime_6144 sets |*ret| to the 6144-bit MODP group from RFC 130 // 3526 and returns |ret|. If |ret| is NULL then a fresh |BIGNUM| is allocated 131 // and returned. It returns NULL on allocation failure. 132 OPENSSL_EXPORT BIGNUM *BN_get_rfc3526_prime_6144(BIGNUM *ret); 133 134 // BN_get_rfc3526_prime_8192 sets |*ret| to the 8192-bit MODP group from RFC 135 // 3526 and returns |ret|. If |ret| is NULL then a fresh |BIGNUM| is allocated 136 // and returned. It returns NULL on allocation failure. 137 OPENSSL_EXPORT BIGNUM *BN_get_rfc3526_prime_8192(BIGNUM *ret); 138 139 140 // Parameter generation. 141 142 #define DH_GENERATOR_2 2 143 #define DH_GENERATOR_5 5 144 145 // DH_generate_parameters_ex generates a suitable Diffie-Hellman group with a 146 // prime that is |prime_bits| long and stores it in |dh|. The generator of the 147 // group will be |generator|, which should be |DH_GENERATOR_2| unless there's a 148 // good reason to use a different value. The |cb| argument contains a callback 149 // function that will be called during the generation. See the documentation in 150 // |bn.h| about this. In addition to the callback invocations from |BN|, |cb| 151 // will also be called with |event| equal to three when the generation is 152 // complete. 153 OPENSSL_EXPORT int DH_generate_parameters_ex(DH *dh, int prime_bits, 154 int generator, BN_GENCB *cb); 155 156 157 // Diffie-Hellman operations. 158 159 // DH_generate_key generates a new, random, private key and stores it in 160 // |dh|, if |dh| does not already have a private key. Otherwise, it updates 161 // |dh|'s public key to match the private key. It returns one on success and 162 // zero on error. 163 OPENSSL_EXPORT int DH_generate_key(DH *dh); 164 165 // DH_compute_key_padded calculates the shared key between |dh| and |peers_key| 166 // and writes it as a big-endian integer into |out|, padded up to |DH_size| 167 // bytes. It returns the number of bytes written, which is always |DH_size|, or 168 // a negative number on error. |out| must have |DH_size| bytes of space. 169 // 170 // WARNING: this differs from the usual BoringSSL return-value convention. 171 // 172 // Note this function differs from |DH_compute_key| in that it preserves leading 173 // zeros in the secret. This function is the preferred variant. It matches PKCS 174 // #3 and avoids some side channel attacks. However, the two functions are not 175 // drop-in replacements for each other. Using a different variant than the 176 // application expects will result in sporadic key mismatches. 177 // 178 // Callers that expect a fixed-width secret should use this function over 179 // |DH_compute_key|. Callers that use either function should migrate to a modern 180 // primitive such as X25519 or ECDH with P-256 instead. 181 // 182 // This function does not mutate |dh| for thread-safety purposes and may be used 183 // concurrently. 184 OPENSSL_EXPORT int DH_compute_key_padded(uint8_t *out, const BIGNUM *peers_key, 185 DH *dh); 186 187 // DH_compute_key_hashed calculates the shared key between |dh| and |peers_key| 188 // and hashes it with the given |digest|. If the hash output is less than 189 // |max_out_len| bytes then it writes the hash output to |out| and sets 190 // |*out_len| to the number of bytes written. Otherwise it signals an error. It 191 // returns one on success or zero on error. 192 // 193 // NOTE: this follows the usual BoringSSL return-value convention, but that's 194 // different from |DH_compute_key| and |DH_compute_key_padded|. 195 // 196 // This function does not mutate |dh| for thread-safety purposes and may be used 197 // concurrently. 198 OPENSSL_EXPORT int DH_compute_key_hashed(DH *dh, uint8_t *out, size_t *out_len, 199 size_t max_out_len, 200 const BIGNUM *peers_key, 201 const EVP_MD *digest); 202 203 204 // Utility functions. 205 206 // DH_size returns the number of bytes in the DH group's prime. 207 OPENSSL_EXPORT int DH_size(const DH *dh); 208 209 // DH_num_bits returns the minimum number of bits needed to represent the 210 // absolute value of the DH group's prime. 211 OPENSSL_EXPORT unsigned DH_num_bits(const DH *dh); 212 213 #define DH_CHECK_P_NOT_PRIME 0x01 214 #define DH_CHECK_P_NOT_SAFE_PRIME 0x02 215 #define DH_CHECK_UNABLE_TO_CHECK_GENERATOR 0x04 216 #define DH_CHECK_NOT_SUITABLE_GENERATOR 0x08 217 #define DH_CHECK_Q_NOT_PRIME 0x10 218 #define DH_CHECK_INVALID_Q_VALUE 0x20 219 220 // These are compatibility defines. 221 #define DH_NOT_SUITABLE_GENERATOR DH_CHECK_NOT_SUITABLE_GENERATOR 222 #define DH_UNABLE_TO_CHECK_GENERATOR DH_CHECK_UNABLE_TO_CHECK_GENERATOR 223 224 // DH_check checks the suitability of |dh| as a Diffie-Hellman group. and sets 225 // |DH_CHECK_*| flags in |*out_flags| if it finds any errors. It returns one if 226 // |*out_flags| was successfully set and zero on error. 227 // 228 // Note: these checks may be quite computationally expensive. 229 OPENSSL_EXPORT int DH_check(const DH *dh, int *out_flags); 230 231 #define DH_CHECK_PUBKEY_TOO_SMALL 0x1 232 #define DH_CHECK_PUBKEY_TOO_LARGE 0x2 233 #define DH_CHECK_PUBKEY_INVALID 0x4 234 235 // DH_check_pub_key checks the suitability of |pub_key| as a public key for the 236 // DH group in |dh| and sets |DH_CHECK_PUBKEY_*| flags in |*out_flags| if it 237 // finds any errors. It returns one if |*out_flags| was successfully set and 238 // zero on error. 239 OPENSSL_EXPORT int DH_check_pub_key(const DH *dh, const BIGNUM *pub_key, 240 int *out_flags); 241 242 // DHparams_dup allocates a fresh |DH| and copies the parameters from |dh| into 243 // it. It returns the new |DH| or NULL on error. 244 OPENSSL_EXPORT DH *DHparams_dup(const DH *dh); 245 246 247 // ASN.1 functions. 248 249 // DH_parse_parameters decodes a DER-encoded DHParameter structure (PKCS #3) 250 // from |cbs| and advances |cbs|. It returns a newly-allocated |DH| or NULL on 251 // error. 252 OPENSSL_EXPORT DH *DH_parse_parameters(CBS *cbs); 253 254 // DH_marshal_parameters marshals |dh| as a DER-encoded DHParameter structure 255 // (PKCS #3) and appends the result to |cbb|. It returns one on success and zero 256 // on error. 257 OPENSSL_EXPORT int DH_marshal_parameters(CBB *cbb, const DH *dh); 258 259 260 // Deprecated functions. 261 262 // DH_generate_parameters behaves like |DH_generate_parameters_ex|, which is 263 // what you should use instead. It returns NULL on error, or a newly-allocated 264 // |DH| on success. This function is provided for compatibility only. 265 OPENSSL_EXPORT DH *DH_generate_parameters(int prime_len, int generator, 266 void (*callback)(int, int, void *), 267 void *cb_arg); 268 269 // d2i_DHparams parses a DER-encoded DHParameter structure (PKCS #3) from |len| 270 // bytes at |*inp|, as in |d2i_SAMPLE|. 271 // 272 // Use |DH_parse_parameters| instead. 273 OPENSSL_EXPORT DH *d2i_DHparams(DH **ret, const unsigned char **inp, long len); 274 275 // i2d_DHparams marshals |in| to a DER-encoded DHParameter structure (PKCS #3), 276 // as described in |i2d_SAMPLE|. 277 // 278 // Use |DH_marshal_parameters| instead. 279 OPENSSL_EXPORT int i2d_DHparams(const DH *in, unsigned char **outp); 280 281 // DH_compute_key behaves like |DH_compute_key_padded| but, contrary to PKCS #3, 282 // returns a variable-length shared key with leading zeros. It returns the 283 // number of bytes written, or a negative number on error. |out| must have 284 // |DH_size| bytes of space. 285 // 286 // WARNING: this differs from the usual BoringSSL return-value convention. 287 // 288 // Note this function's running time and memory access pattern leaks information 289 // about the shared secret. Particularly if |dh| is reused, this may result in 290 // side channel attacks such as https://raccoon-attack.com/. 291 // 292 // |DH_compute_key_padded| is the preferred variant and avoids the above 293 // attacks. However, the two functions are not drop-in replacements for each 294 // other. Using a different variant than the application expects will result in 295 // sporadic key mismatches. 296 // 297 // Callers that expect a fixed-width secret should use |DH_compute_key_padded| 298 // instead. Callers that use either function should migrate to a modern 299 // primitive such as X25519 or ECDH with P-256 instead. 300 // 301 // This function does not mutate |dh| for thread-safety purposes and may be used 302 // concurrently. 303 OPENSSL_EXPORT int DH_compute_key(uint8_t *out, const BIGNUM *peers_key, 304 DH *dh); 305 306 307 #if defined(__cplusplus) 308 } // extern C 309 310 extern "C++" { 311 312 BSSL_NAMESPACE_BEGIN 313 314 BORINGSSL_MAKE_DELETER(DH, DH_free) 315 BORINGSSL_MAKE_UP_REF(DH, DH_up_ref) 316 317 BSSL_NAMESPACE_END 318 319 } // extern C++ 320 321 #endif 322 323 #define DH_R_BAD_GENERATOR 100 324 #define DH_R_INVALID_PUBKEY 101 325 #define DH_R_MODULUS_TOO_LARGE 102 326 #define DH_R_NO_PRIVATE_VALUE 103 327 #define DH_R_DECODE_ERROR 104 328 #define DH_R_ENCODE_ERROR 105 329 #define DH_R_INVALID_PARAMETERS 106 330 331 #endif // OPENSSL_HEADER_DH_H 332