crypto/heimdal/doc/doxyout/hcrypto/man/man3/hcrypto_dh.3

   1 .TH "Diffie-Hellman functions" 3 "11 Jan 2012" "Version 1.5.2" "Heimdal crypto library" \" -*- nroff -*-
   2 .ad l
   3 .nh
   4 .SH NAME
   5 Diffie-Hellman functions \-
   6 .SS "Functions"
   7
   8 .in +1c
   9 .ti -1c
  10 .RI "const DH_METHOD * \fBDH_ltm_method\fP (void)"
  11 .br
  12 .ti -1c
  13 .RI "DH * \fBDH_new\fP (void)"
  14 .br
  15 .ti -1c
  16 .RI "DH * \fBDH_new_method\fP (ENGINE *engine)"
  17 .br
  18 .ti -1c
  19 .RI "void \fBDH_free\fP (DH *dh)"
  20 .br
  21 .ti -1c
  22 .RI "int \fBDH_up_ref\fP (DH *dh)"
  23 .br
  24 .ti -1c
  25 .RI "int \fBDH_size\fP (const DH *dh)"
  26 .br
  27 .ti -1c
  28 .RI "int \fBDH_set_ex_data\fP (DH *dh, int idx, void *data)"
  29 .br
  30 .ti -1c
  31 .RI "void * \fBDH_get_ex_data\fP (DH *dh, int idx)"
  32 .br
  33 .ti -1c
  34 .RI "int \fBDH_generate_parameters_ex\fP (DH *dh, int prime_len, int generator, BN_GENCB *cb)"
  35 .br
  36 .ti -1c
  37 .RI "int \fBDH_check_pubkey\fP (const DH *dh, const BIGNUM *pub_key, int *codes)"
  38 .br
  39 .ti -1c
  40 .RI "int \fBDH_generate_key\fP (DH *dh)"
  41 .br
  42 .ti -1c
  43 .RI "int \fBDH_compute_key\fP (unsigned char *shared_key, const BIGNUM *peer_pub_key, DH *dh)"
  44 .br
  45 .ti -1c
  46 .RI "int \fBDH_set_method\fP (DH *dh, const DH_METHOD *method)"
  47 .br
  48 .ti -1c
  49 .RI "const DH_METHOD * \fBDH_null_method\fP (void)"
  50 .br
  51 .ti -1c
  52 .RI "void \fBDH_set_default_method\fP (const DH_METHOD *meth)"
  53 .br
  54 .ti -1c
  55 .RI "const DH_METHOD * \fBDH_get_default_method\fP (void)"
  56 .br
  57 .in -1c
  58 .SH "Detailed Description"
  59 .PP
  60 See the \fBDH - Diffie-Hellman key exchange\fP for description and examples.
  61 .SH "Function Documentation"
  62 .PP
  63 .SS "int DH_check_pubkey (const DH * dh, const BIGNUM * pub_key, int * codes)"
  64 .PP
  65 Check that the public key is sane.
  66 .PP
  67 \fBParameters:\fP
  68 .RS 4
  69 \fIdh\fP the local peer DH parameters.
  70 .br
  71 \fIpub_key\fP the remote peer public key parameters.
  72 .br
  73 \fIcodes\fP return that the failures of the pub_key are.
  74 .RE
  75 .PP
  76 \fBReturns:\fP
  77 .RS 4
  78 1 on success, 0 on failure and *codes is set the the combined fail check for the public key
  79 .RE
  80 .PP
  81
  82 .PP
  83 Checks that the function performs are:
  84 .IP "\(bu" 2
  85 pub_key is not negative
  86 .PP
  87 .PP
  88 .IP "\(bu" 2
  89 pub_key > 1 and pub_key < p - 1, to avoid small subgroups attack.
  90 .PP
  91 .PP
  92 .IP "\(bu" 2
  93 if g == 2, pub_key have more then one bit set, if bits set is 1, log_2(pub_key) is trival
  94 .PP
  95
  96 .SS "int DH_compute_key (unsigned char * shared_key, const BIGNUM * peer_pub_key, DH * dh)"
  97 .PP
  98 Complute the shared secret key.
  99 .PP
 100 \fBParameters:\fP
 101 .RS 4
 102 \fIshared_key\fP the resulting shared key, need to be at least \fBDH_size()\fP large.
 103 .br
 104 \fIpeer_pub_key\fP the peer's public key.
 105 .br
 106 \fIdh\fP the dh key pair.
 107 .RE
 108 .PP
 109 \fBReturns:\fP
 110 .RS 4
 111 1 on success.
 112 .RE
 113 .PP
 114
 115 .PP
 116 Checks that the pubkey passed in is valid using \fBDH_check_pubkey()\fP.
 117 .SS "void DH_free (DH * dh)"
 118 .PP
 119 Free a DH object and release related resources, like ENGINE, that the object was using.
 120 .PP
 121 \fBParameters:\fP
 122 .RS 4
 123 \fIdh\fP object to be freed.
 124 .RE
 125 .PP
 126
 127 .SS "int DH_generate_key (DH * dh)"
 128 .PP
 129 Generate a new DH private-public key pair. The dh parameter must be allocted first with \fBDH_new()\fP. dh->p and dp->g must be set.
 130 .PP
 131 \fBParameters:\fP
 132 .RS 4
 133 \fIdh\fP dh parameter.
 134 .RE
 135 .PP
 136 \fBReturns:\fP
 137 .RS 4
 138 1 on success.
 139 .RE
 140 .PP
 141
 142 .SS "int DH_generate_parameters_ex (DH * dh, int prime_len, int generator, BN_GENCB * cb)"
 143 .PP
 144 Generate DH parameters for the DH object give parameters.
 145 .PP
 146 \fBParameters:\fP
 147 .RS 4
 148 \fIdh\fP The DH object to generate parameters for.
 149 .br
 150 \fIprime_len\fP length of the prime
 151 .br
 152 \fIgenerator\fP generator, g
 153 .br
 154 \fIcb\fP Callback parameters to show progress, can be NULL.
 155 .RE
 156 .PP
 157 \fBReturns:\fP
 158 .RS 4
 159 the maximum size in bytes of the out data.
 160 .RE
 161 .PP
 162
 163 .SS "const DH_METHOD* DH_get_default_method (void)"
 164 .PP
 165 Return the default DH implementation.
 166 .PP
 167 \fBReturns:\fP
 168 .RS 4
 169 pointer to a DH_METHOD.
 170 .RE
 171 .PP
 172
 173 .SS "void* DH_get_ex_data (DH * dh, int idx)"
 174 .PP
 175 Get the data for index idx in the DH object.
 176 .PP
 177 \fBParameters:\fP
 178 .RS 4
 179 \fIdh\fP DH object.
 180 .br
 181 \fIidx\fP index to get the data for.
 182 .RE
 183 .PP
 184 \fBReturns:\fP
 185 .RS 4
 186 the object store in index idx
 187 .RE
 188 .PP
 189
 190 .SS "const DH_METHOD* DH_ltm_method (void)"
 191 .PP
 192 DH implementation using libtommath.
 193 .PP
 194 \fBReturns:\fP
 195 .RS 4
 196 the DH_METHOD for the DH implementation using libtommath.
 197 .RE
 198 .PP
 199
 200 .SS "DH* DH_new (void)"
 201 .PP
 202 Create a new DH object using DH_new_method(NULL), see \fBDH_new_method()\fP.
 203 .PP
 204 \fBReturns:\fP
 205 .RS 4
 206 a newly allocated DH object.
 207 .RE
 208 .PP
 209
 210 .SS "DH* DH_new_method (ENGINE * engine)"
 211 .PP
 212 Create a new DH object from the given engine, if the NULL is used, the default engine is used. Free the DH object with \fBDH_free()\fP.
 213 .PP
 214 \fBParameters:\fP
 215 .RS 4
 216 \fIengine\fP The engine to use to allocate the DH object.
 217 .RE
 218 .PP
 219 \fBReturns:\fP
 220 .RS 4
 221 a newly allocated DH object.
 222 .RE
 223 .PP
 224
 225 .SS "const DH_METHOD* DH_null_method (void)"
 226 .PP
 227 Return the dummy DH implementation.
 228 .PP
 229 \fBReturns:\fP
 230 .RS 4
 231 pointer to a DH_METHOD.
 232 .RE
 233 .PP
 234
 235 .SS "void DH_set_default_method (const DH_METHOD * meth)"
 236 .PP
 237 Set the default DH implementation.
 238 .PP
 239 \fBParameters:\fP
 240 .RS 4
 241 \fImeth\fP pointer to a DH_METHOD.
 242 .RE
 243 .PP
 244
 245 .SS "int DH_set_ex_data (DH * dh, int idx, void * data)"
 246 .PP
 247 Set the data index idx in the DH object to data.
 248 .PP
 249 \fBParameters:\fP
 250 .RS 4
 251 \fIdh\fP DH object.
 252 .br
 253 \fIidx\fP index to set the data for.
 254 .br
 255 \fIdata\fP data to store for the index idx.
 256 .RE
 257 .PP
 258 \fBReturns:\fP
 259 .RS 4
 260 1 on success.
 261 .RE
 262 .PP
 263
 264 .SS "int DH_set_method (DH * dh, const DH_METHOD * method)"
 265 .PP
 266 Set a new method for the DH keypair.
 267 .PP
 268 \fBParameters:\fP
 269 .RS 4
 270 \fIdh\fP dh parameter.
 271 .br
 272 \fImethod\fP the new method for the DH parameter.
 273 .RE
 274 .PP
 275 \fBReturns:\fP
 276 .RS 4
 277 1 on success.
 278 .RE
 279 .PP
 280
 281 .SS "int DH_size (const DH * dh)"
 282 .PP
 283 The maximum output size of the \fBDH_compute_key()\fP function.
 284 .PP
 285 \fBParameters:\fP
 286 .RS 4
 287 \fIdh\fP The DH object to get the size from.
 288 .RE
 289 .PP
 290 \fBReturns:\fP
 291 .RS 4
 292 the maximum size in bytes of the out data.
 293 .RE
 294 .PP
 295
 296 .SS "int DH_up_ref (DH * dh)"
 297 .PP
 298 Add a reference to the DH object. The object should be free with \fBDH_free()\fP to drop the reference.
 299 .PP
 300 \fBParameters:\fP
 301 .RS 4
 302 \fIdh\fP the object to increase the reference count too.
 303 .RE
 304 .PP
 305 \fBReturns:\fP
 306 .RS 4
 307 the updated reference count, can't safely be used except for debug printing.
 308 .RE
 309 .PP
 310