f4401cd869
alter des.h to be friendly with openssl/des.h (you can include both in the same file) make libkrb to depend on libdes. bump major. massage various portioin of heimdal to be friendly with openssl 0.9.7b.
281 lines
9.4 KiB
Groff
281 lines
9.4 KiB
Groff
.\" $NetBSD: DH_set_method.3,v 1.12 2003/07/24 14:16:38 itojun Exp $
|
|
.\"
|
|
.\" Automatically generated by Pod::Man version 1.02
|
|
.\" Thu Jul 24 13:07:53 2003
|
|
.\"
|
|
.\" Standard preamble:
|
|
.\" ======================================================================
|
|
.de Sh \" Subsection heading
|
|
.br
|
|
.if t .Sp
|
|
.ne 5
|
|
.PP
|
|
\fB\\$1\fR
|
|
.PP
|
|
..
|
|
.de Sp \" Vertical space (when we can't use .PP)
|
|
.if t .sp .5v
|
|
.if n .sp
|
|
..
|
|
.de Ip \" List item
|
|
.br
|
|
.ie \\n(.$>=3 .ne \\$3
|
|
.el .ne 3
|
|
.IP "\\$1" \\$2
|
|
..
|
|
.de Vb \" Begin verbatim text
|
|
.ft CW
|
|
.nf
|
|
.ne \\$1
|
|
..
|
|
.de Ve \" End verbatim text
|
|
.ft R
|
|
|
|
.fi
|
|
..
|
|
.\" Set up some character translations and predefined strings. \*(-- will
|
|
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
|
|
.\" double quote, and \*(R" will give a right double quote. | will give a
|
|
.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used
|
|
.\" to do unbreakable dashes and therefore won't be available. \*(C` and
|
|
.\" \*(C' expand to `' in nroff, nothing in troff, for use with C<>
|
|
.tr \(*W-|\(bv\*(Tr
|
|
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
|
|
.ie n \{\
|
|
. ds -- \(*W-
|
|
. ds PI pi
|
|
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
|
|
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
|
|
. ds L" ""
|
|
. ds R" ""
|
|
. ds C` `
|
|
. ds C' '
|
|
'br\}
|
|
.el\{\
|
|
. ds -- \|\(em\|
|
|
. ds PI \(*p
|
|
. ds L" ``
|
|
. ds R" ''
|
|
'br\}
|
|
.\"
|
|
.\" If the F register is turned on, we'll generate index entries on stderr
|
|
.\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and
|
|
.\" index entries marked with X<> in POD. Of course, you'll have to process
|
|
.\" the output yourself in some meaningful fashion.
|
|
.if \nF \{\
|
|
. de IX
|
|
. tm Index:\\$1\t\\n%\t"\\$2"
|
|
. .
|
|
. nr % 0
|
|
. rr F
|
|
.\}
|
|
.\"
|
|
.\" For nroff, turn off justification. Always turn off hyphenation; it
|
|
.\" makes way too many mistakes in technical documents.
|
|
.hy 0
|
|
.if n .na
|
|
.\"
|
|
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
|
|
.\" Fear. Run. Save yourself. No user-serviceable parts.
|
|
.bd B 3
|
|
. \" fudge factors for nroff and troff
|
|
.if n \{\
|
|
. ds #H 0
|
|
. ds #V .8m
|
|
. ds #F .3m
|
|
. ds #[ \f1
|
|
. ds #] \fP
|
|
.\}
|
|
.if t \{\
|
|
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
|
|
. ds #V .6m
|
|
. ds #F 0
|
|
. ds #[ \&
|
|
. ds #] \&
|
|
.\}
|
|
. \" simple accents for nroff and troff
|
|
.if n \{\
|
|
. ds ' \&
|
|
. ds ` \&
|
|
. ds ^ \&
|
|
. ds , \&
|
|
. ds ~ ~
|
|
. ds /
|
|
.\}
|
|
.if t \{\
|
|
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
|
|
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
|
|
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
|
|
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
|
|
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
|
|
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
|
|
.\}
|
|
. \" troff and (daisy-wheel) nroff accents
|
|
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
|
|
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
|
|
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
|
|
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
|
|
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
|
|
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
|
|
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
|
|
.ds ae a\h'-(\w'a'u*4/10)'e
|
|
.ds Ae A\h'-(\w'A'u*4/10)'E
|
|
. \" corrections for vroff
|
|
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
|
|
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
|
|
. \" for low resolution devices (crt and lpr)
|
|
.if \n(.H>23 .if \n(.V>19 \
|
|
\{\
|
|
. ds : e
|
|
. ds 8 ss
|
|
. ds o a
|
|
. ds d- d\h'-1'\(ga
|
|
. ds D- D\h'-1'\(hy
|
|
. ds th \o'bp'
|
|
. ds Th \o'LP'
|
|
. ds ae ae
|
|
. ds Ae AE
|
|
.\}
|
|
.rm #[ #] #H #V #F C
|
|
.\" ======================================================================
|
|
.\"
|
|
.IX Title "DH_set_method 3"
|
|
.TH DH_set_method 3 "0.9.7b" "2002-10-29" "OpenSSL"
|
|
.UC
|
|
.SH "NAME"
|
|
DH_set_default_method, DH_get_default_method,
|
|
DH_set_method, DH_new_method, DH_OpenSSL \- select \s-1DH\s0 method
|
|
.SH "LIBRARY"
|
|
libcrypto, -lcrypto
|
|
.SH "SYNOPSIS"
|
|
.IX Header "SYNOPSIS"
|
|
.Vb 2
|
|
\& #include <openssl/dh.h>
|
|
\& #include <openssl/engine.h>
|
|
.Ve
|
|
.Vb 1
|
|
\& void DH_set_default_method(const DH_METHOD *meth);
|
|
.Ve
|
|
.Vb 1
|
|
\& const DH_METHOD *DH_get_default_method(void);
|
|
.Ve
|
|
.Vb 1
|
|
\& int DH_set_method(DH *dh, const DH_METHOD *meth);
|
|
.Ve
|
|
.Vb 1
|
|
\& DH *DH_new_method(ENGINE *engine);
|
|
.Ve
|
|
.Vb 1
|
|
\& const DH_METHOD *DH_OpenSSL(void);
|
|
.Ve
|
|
.SH "DESCRIPTION"
|
|
.IX Header "DESCRIPTION"
|
|
A \fB\s-1DH_METHOD\s0\fR specifies the functions that OpenSSL uses for Diffie-Hellman
|
|
operations. By modifying the method, alternative implementations
|
|
such as hardware accelerators may be used. \s-1IMPORTANT:\s0 See the \s-1NOTES\s0 section for
|
|
important information about how these \s-1DH\s0 \s-1API\s0 functions are affected by the use
|
|
of \fB\s-1ENGINE\s0\fR \s-1API\s0 calls.
|
|
.PP
|
|
Initially, the default \s-1DH_METHOD\s0 is the OpenSSL internal implementation, as
|
|
returned by \fIDH_OpenSSL()\fR.
|
|
.PP
|
|
\&\fIDH_set_default_method()\fR makes \fBmeth\fR the default method for all \s-1DH\s0
|
|
structures created later. \fB\s-1NB\s0\fR: This is true only whilst no \s-1ENGINE\s0 has been set
|
|
as a default for \s-1DH\s0, so this function is no longer recommended.
|
|
.PP
|
|
\&\fIDH_get_default_method()\fR returns a pointer to the current default \s-1DH_METHOD\s0.
|
|
However, the meaningfulness of this result is dependant on whether the \s-1ENGINE\s0
|
|
\&\s-1API\s0 is being used, so this function is no longer recommended.
|
|
.PP
|
|
\&\fIDH_set_method()\fR selects \fBmeth\fR to perform all operations using the key \fBdh\fR.
|
|
This will replace the \s-1DH_METHOD\s0 used by the \s-1DH\s0 key and if the previous method
|
|
was supplied by an \s-1ENGINE\s0, the handle to that \s-1ENGINE\s0 will be released during the
|
|
change. It is possible to have \s-1DH\s0 keys that only work with certain \s-1DH_METHOD\s0
|
|
implementations (eg. from an \s-1ENGINE\s0 module that supports embedded
|
|
hardware-protected keys), and in such cases attempting to change the \s-1DH_METHOD\s0
|
|
for the key can have unexpected results.
|
|
.PP
|
|
\&\fIDH_new_method()\fR allocates and initializes a \s-1DH\s0 structure so that \fBengine\fR will
|
|
be used for the \s-1DH\s0 operations. If \fBengine\fR is \s-1NULL\s0, the default \s-1ENGINE\s0 for \s-1DH\s0
|
|
operations is used, and if no default \s-1ENGINE\s0 is set, the \s-1DH_METHOD\s0 controlled by
|
|
\&\fIDH_set_default_method()\fR is used.
|
|
.SH "THE DH_METHOD STRUCTURE"
|
|
.IX Header "THE DH_METHOD STRUCTURE"
|
|
.Vb 4
|
|
\& typedef struct dh_meth_st
|
|
\& {
|
|
\& /* name of the implementation */
|
|
\& const char *name;
|
|
.Ve
|
|
.Vb 2
|
|
\& /* generate private and public DH values for key agreement */
|
|
\& int (*generate_key)(DH *dh);
|
|
.Ve
|
|
.Vb 2
|
|
\& /* compute shared secret */
|
|
\& int (*compute_key)(unsigned char *key, BIGNUM *pub_key, DH *dh);
|
|
.Ve
|
|
.Vb 4
|
|
\& /* compute r = a ^ p mod m (May be NULL for some implementations) */
|
|
\& int (*bn_mod_exp)(DH *dh, BIGNUM *r, BIGNUM *a, const BIGNUM *p,
|
|
\& const BIGNUM *m, BN_CTX *ctx,
|
|
\& BN_MONT_CTX *m_ctx);
|
|
.Ve
|
|
.Vb 2
|
|
\& /* called at DH_new */
|
|
\& int (*init)(DH *dh);
|
|
.Ve
|
|
.Vb 2
|
|
\& /* called at DH_free */
|
|
\& int (*finish)(DH *dh);
|
|
.Ve
|
|
.Vb 1
|
|
\& int flags;
|
|
.Ve
|
|
.Vb 1
|
|
\& char *app_data; /* ?? */
|
|
.Ve
|
|
.Vb 1
|
|
\& } DH_METHOD;
|
|
.Ve
|
|
.SH "RETURN VALUES"
|
|
.IX Header "RETURN VALUES"
|
|
\&\fIDH_OpenSSL()\fR and \fIDH_get_default_method()\fR return pointers to the respective
|
|
\&\fB\s-1DH_METHOD\s0\fRs.
|
|
.PP
|
|
\&\fIDH_set_default_method()\fR returns no value.
|
|
.PP
|
|
\&\fIDH_set_method()\fR returns non-zero if the provided \fBmeth\fR was successfully set as
|
|
the method for \fBdh\fR (including unloading the \s-1ENGINE\s0 handle if the previous
|
|
method was supplied by an \s-1ENGINE\s0).
|
|
.PP
|
|
\&\fIDH_new_method()\fR returns \s-1NULL\s0 and sets an error code that can be obtained by
|
|
ERR_get_error(3) if the allocation fails. Otherwise it
|
|
returns a pointer to the newly allocated structure.
|
|
.SH "NOTES"
|
|
.IX Header "NOTES"
|
|
As of version 0.9.7, \s-1DH_METHOD\s0 implementations are grouped together with other
|
|
algorithmic APIs (eg. \s-1RSA_METHOD\s0, \s-1EVP_CIPHER\s0, etc) in \fB\s-1ENGINE\s0\fR modules. If a
|
|
default \s-1ENGINE\s0 is specified for \s-1DH\s0 functionality using an \s-1ENGINE\s0 \s-1API\s0 function,
|
|
that will override any \s-1DH\s0 defaults set using the \s-1DH\s0 \s-1API\s0 (ie.
|
|
\&\fIDH_set_default_method()\fR). For this reason, the \s-1ENGINE\s0 \s-1API\s0 is the recommended way
|
|
to control default implementations for use in \s-1DH\s0 and other cryptographic
|
|
algorithms.
|
|
.SH "SEE ALSO"
|
|
.IX Header "SEE ALSO"
|
|
openssl_dh(3), DH_new(3)
|
|
.SH "HISTORY"
|
|
.IX Header "HISTORY"
|
|
\&\fIDH_set_default_method()\fR, \fIDH_get_default_method()\fR, \fIDH_set_method()\fR,
|
|
\&\fIDH_new_method()\fR and \fIDH_OpenSSL()\fR were added in OpenSSL 0.9.4.
|
|
.PP
|
|
\&\fIDH_set_default_openssl_method()\fR and \fIDH_get_default_openssl_method()\fR replaced
|
|
\&\fIDH_set_default_method()\fR and \fIDH_get_default_method()\fR respectively, and
|
|
\&\fIDH_set_method()\fR and \fIDH_new_method()\fR were altered to use \fB\s-1ENGINE\s0\fRs rather than
|
|
\&\fB\s-1DH_METHOD\s0\fRs during development of the engine version of OpenSSL 0.9.6. For
|
|
0.9.7, the handling of defaults in the \s-1ENGINE\s0 \s-1API\s0 was restructured so that this
|
|
change was reversed, and behaviour of the other functions resembled more closely
|
|
the previous behaviour. The behaviour of defaults in the \s-1ENGINE\s0 \s-1API\s0 now
|
|
transparently overrides the behaviour of defaults in the \s-1DH\s0 \s-1API\s0 without
|
|
requiring changing these function prototypes.
|