secure/lib/libcrypto/man/dh.3

   1 .rn '' }`
   2 ''' $RCSfile$$Revision$$Date$
   3 '''
   4 ''' $Log$
   5 '''
   6 .de Sh
   7 .br
   8 .if t .Sp
   9 .ne 5
  10 .PP
  11 \fB\\$1\fR
  12 .PP
  13 ..
  14 .de Sp
  15 .if t .sp .5v
  16 .if n .sp
  17 ..
  18 .de Ip
  19 .br
  20 .ie \\n(.$>=3 .ne \\$3
  21 .el .ne 3
  22 .IP "\\$1" \\$2
  23 ..
  24 .de Vb
  25 .ft CW
  26 .nf
  27 .ne \\$1
  28 ..
  29 .de Ve
  30 .ft R
  31
  32 .fi
  33 ..
  34 '''
  35 '''
  36 '''     Set up \*(-- to give an unbreakable dash;
  37 '''     string Tr holds user defined translation string.
  38 '''     Bell System Logo is used as a dummy character.
  39 '''
  40 .tr \(*W-|\(bv\*(Tr
  41 .ie n \{\
  42 .ds -- \(*W-
  43 .ds PI pi
  44 .if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  45 .if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
  46 .ds L" ""
  47 .ds R" ""
  48 '''   \*(M", \*(S", \*(N" and \*(T" are the equivalent of
  49 '''   \*(L" and \*(R", except that they are used on ".xx" lines,
  50 '''   such as .IP and .SH, which do another additional levels of
  51 '''   double-quote interpretation
  52 .ds M" """
  53 .ds S" """
  54 .ds N" """""
  55 .ds T" """""
  56 .ds L' '
  57 .ds R' '
  58 .ds M' '
  59 .ds S' '
  60 .ds N' '
  61 .ds T' '
  62 'br\}
  63 .el\{\
  64 .ds -- \(em\|
  65 .tr \*(Tr
  66 .ds L" ``
  67 .ds R" ''
  68 .ds M" ``
  69 .ds S" ''
  70 .ds N" ``
  71 .ds T" ''
  72 .ds L' `
  73 .ds R' '
  74 .ds M' `
  75 .ds S' '
  76 .ds N' `
  77 .ds T' '
  78 .ds PI \(*p
  79 'br\}
  80 .\"     If the F register is turned on, we'll generate
  81 .\"     index entries out stderr for the following things:
  82 .\"             TH      Title
  83 .\"             SH      Header
  84 .\"             Sh      Subsection
  85 .\"             Ip      Item
  86 .\"             X<>     Xref  (embedded
  87 .\"     Of course, you have to process the output yourself
  88 .\"     in some meaninful fashion.
  89 .if \nF \{
  90 .de IX
  91 .tm Index:\\$1\t\\n%\t"\\$2"
  92 ..
  93 .nr % 0
  94 .rr F
  95 .\}
  96 .TH dh 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
  97 .UC
  98 .if n .hy 0
  99 .if n .na
 100 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
 101 .de CQ          \" put $1 in typewriter font
 102 .ft CW
 103 'if n "\c
 104 'if t \\&\\$1\c
 105 'if n \\&\\$1\c
 106 'if n \&"
 107 \\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
 108 '.ft R
 109 ..
 110 .\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
 111 .       \" AM - accent mark definitions
 112 .bd B 3
 113 .       \" fudge factors for nroff and troff
 114 .if n \{\
 115 .       ds #H 0
 116 .       ds #V .8m
 117 .       ds #F .3m
 118 .       ds #[ \f1
 119 .       ds #] \fP
 120 .\}
 121 .if t \{\
 122 .       ds #H ((1u-(\\\\n(.fu%2u))*.13m)
 123 .       ds #V .6m
 124 .       ds #F 0
 125 .       ds #[ \&
 126 .       ds #] \&
 127 .\}
 128 .       \" simple accents for nroff and troff
 129 .if n \{\
 130 .       ds ' \&
 131 .       ds ` \&
 132 .       ds ^ \&
 133 .       ds , \&
 134 .       ds ~ ~
 135 .       ds ? ?
 136 .       ds ! !
 137 .       ds /
 138 .       ds q
 139 .\}
 140 .if t \{\
 141 .       ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 142 .       ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 143 .       ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 144 .       ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 145 .       ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 146 .       ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
 147 .       ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
 148 .       ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 149 .       ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
 150 .\}
 151 .       \" troff and (daisy-wheel) nroff accents
 152 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 153 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 154 .ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
 155 .ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
 156 .ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
 157 .ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
 158 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 159 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 160 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 161 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 162 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 163 .ds ae a\h'-(\w'a'u*4/10)'e
 164 .ds Ae A\h'-(\w'A'u*4/10)'E
 165 .ds oe o\h'-(\w'o'u*4/10)'e
 166 .ds Oe O\h'-(\w'O'u*4/10)'E
 167 .       \" corrections for vroff
 168 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 169 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 170 .       \" for low resolution devices (crt and lpr)
 171 .if \n(.H>23 .if \n(.V>19 \
 172 \{\
 173 .       ds : e
 174 .       ds 8 ss
 175 .       ds v \h'-1'\o'\(aa\(ga'
 176 .       ds _ \h'-1'^
 177 .       ds . \h'-1'.
 178 .       ds 3 3
 179 .       ds o a
 180 .       ds d- d\h'-1'\(ga
 181 .       ds D- D\h'-1'\(hy
 182 .       ds th \o'bp'
 183 .       ds Th \o'LP'
 184 .       ds ae ae
 185 .       ds Ae AE
 186 .       ds oe oe
 187 .       ds Oe OE
 188 .\}
 189 .rm #[ #] #H #V #F C
 190 .SH "NAME"
 191 dh \- Diffie-Hellman key agreement
 192 .SH "SYNOPSIS"
 193 .PP
 194 .Vb 2
 195 \& #include <openssl/dh.h>
 196 \& #include <openssl/engine.h>
 197 .Ve
 198 .Vb 2
 199 \& DH *   DH_new(void);
 200 \& void   DH_free(DH *dh);
 201 .Ve
 202 .Vb 1
 203 \& int    DH_size(const DH *dh);
 204 .Ve
 205 .Vb 3
 206 \& DH *   DH_generate_parameters(int prime_len, int generator,
 207 \&                void (*callback)(int, int, void *), void *cb_arg);
 208 \& int    DH_check(const DH *dh, int *codes);
 209 .Ve
 210 .Vb 2
 211 \& int    DH_generate_key(DH *dh);
 212 \& int    DH_compute_key(unsigned char *key, BIGNUM *pub_key, DH *dh);
 213 .Ve
 214 .Vb 5
 215 \& void DH_set_default_method(const DH_METHOD *meth);
 216 \& const DH_METHOD *DH_get_default_method(void);
 217 \& int DH_set_method(DH *dh, const DH_METHOD *meth);
 218 \& DH *DH_new_method(ENGINE *engine);
 219 \& const DH_METHOD *DH_OpenSSL(void);
 220 .Ve
 221 .Vb 4
 222 \& int DH_get_ex_new_index(long argl, char *argp, int (*new_func)(),
 223 \&             int (*dup_func)(), void (*free_func)());
 224 \& int DH_set_ex_data(DH *d, int idx, char *arg);
 225 \& char *DH_get_ex_data(DH *d, int idx);
 226 .Ve
 227 .Vb 2
 228 \& DH *   d2i_DHparams(DH **a, unsigned char **pp, long length);
 229 \& int    i2d_DHparams(const DH *a, unsigned char **pp);
 230 .Ve
 231 .Vb 2
 232 \& int    DHparams_print_fp(FILE *fp, const DH *x);
 233 \& int    DHparams_print(BIO *bp, const DH *x);
 234 .Ve
 235 .SH "DESCRIPTION"
 236 These functions implement the Diffie-Hellman key agreement protocol.
 237 The generation of shared DH parameters is described in
 238 DH_generate_parameters(3); DH_generate_key(3) describes how
 239 to perform a key agreement.
 240 .PP
 241 The \fBDH\fR structure consists of several BIGNUM components.
 242 .PP
 243 .Vb 9
 244 \& struct
 245 \&        {
 246 \&        BIGNUM *p;              // prime number (shared)
 247 \&        BIGNUM *g;              // generator of Z_p (shared)
 248 \&        BIGNUM *priv_key;       // private DH value x
 249 \&        BIGNUM *pub_key;        // public DH value g^x
 250 \&        // ...
 251 \&        };
 252 \& DH
 253 .Ve
 254 Note that DH keys may use non-standard \fBDH_METHOD\fR implementations,
 255 either directly or by the use of \fBENGINE\fR modules. In some cases (eg. an
 256 ENGINE providing support for hardware-embedded keys), these BIGNUM values
 257 will not be used by the implementation or may be used for alternative data
 258 storage. For this reason, applications should generally avoid using DH
 259 structure elements directly and instead use API functions to query or
 260 modify keys.
 261 .SH "SEE ALSO"
 262 dhparam(1), bn(3), dsa(3), err(3),
 263 rand(3), rsa(3), engine(3),
 264 DH_set_method(3), DH_new(3),
 265 DH_get_ex_new_index(3),
 266 DH_generate_parameters(3),
 267 DH_compute_key(3), d2i_DHparams(3),
 268 RSA_print(3)
 269
 270 .rn }` ''
 271 .IX Title "dh 3"
 272 .IX Name "dh - Diffie-Hellman key agreement"
 273
 274 .IX Header "NAME"
 275
 276 .IX Header "SYNOPSIS"
 277
 278 .IX Header "DESCRIPTION"
 279
 280 .IX Header "SEE ALSO"
 281