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.
296 lines
10 KiB
Groff
296 lines
10 KiB
Groff
.\" $NetBSD: DSA_set_method.3,v 1.12 2003/07/24 14:16:39 itojun Exp $
|
|
.\"
|
|
.\" Automatically generated by Pod::Man version 1.02
|
|
.\" Thu Jul 24 13:07:55 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 "DSA_set_method 3"
|
|
.TH DSA_set_method 3 "0.9.7b" "2002-10-29" "OpenSSL"
|
|
.UC
|
|
.SH "NAME"
|
|
DSA_set_default_method, DSA_get_default_method,
|
|
DSA_set_method, DSA_new_method, DSA_OpenSSL \- select \s-1DSA\s0 method
|
|
.SH "LIBRARY"
|
|
libcrypto, -lcrypto
|
|
.SH "SYNOPSIS"
|
|
.IX Header "SYNOPSIS"
|
|
.Vb 2
|
|
\& #include <openssl/dsa.h>
|
|
\& #include <openssl/engine.h>
|
|
.Ve
|
|
.Vb 1
|
|
\& void DSA_set_default_method(const DSA_METHOD *meth);
|
|
.Ve
|
|
.Vb 1
|
|
\& const DSA_METHOD *DSA_get_default_method(void);
|
|
.Ve
|
|
.Vb 1
|
|
\& int DSA_set_method(DSA *dsa, const DSA_METHOD *meth);
|
|
.Ve
|
|
.Vb 1
|
|
\& DSA *DSA_new_method(ENGINE *engine);
|
|
.Ve
|
|
.Vb 1
|
|
\& DSA_METHOD *DSA_OpenSSL(void);
|
|
.Ve
|
|
.SH "DESCRIPTION"
|
|
.IX Header "DESCRIPTION"
|
|
A \fB\s-1DSA_METHOD\s0\fR specifies the functions that OpenSSL uses for \s-1DSA\s0
|
|
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-1DSA\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-1DSA_METHOD\s0 is the OpenSSL internal implementation,
|
|
as returned by \fIDSA_OpenSSL()\fR.
|
|
.PP
|
|
\&\fIDSA_set_default_method()\fR makes \fBmeth\fR the default method for all \s-1DSA\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-1DSA\s0, so this function is no longer recommended.
|
|
.PP
|
|
\&\fIDSA_get_default_method()\fR returns a pointer to the current default
|
|
\&\s-1DSA_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
|
|
\&\fIDSA_set_method()\fR selects \fBmeth\fR to perform all operations using the key
|
|
\&\fBrsa\fR. This will replace the \s-1DSA_METHOD\s0 used by the \s-1DSA\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-1DSA\s0 keys that only
|
|
work with certain \s-1DSA_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-1DSA_METHOD\s0 for the key can have unexpected
|
|
results.
|
|
.PP
|
|
\&\fIDSA_new_method()\fR allocates and initializes a \s-1DSA\s0 structure so that \fBengine\fR
|
|
will be used for the \s-1DSA\s0 operations. If \fBengine\fR is \s-1NULL\s0, the default engine
|
|
for \s-1DSA\s0 operations is used, and if no default \s-1ENGINE\s0 is set, the \s-1DSA_METHOD\s0
|
|
controlled by \fIDSA_set_default_method()\fR is used.
|
|
.SH "THE DSA_METHOD STRUCTURE"
|
|
.IX Header "THE DSA_METHOD STRUCTURE"
|
|
struct
|
|
{
|
|
/* name of the implementation */
|
|
const char *name;
|
|
.PP
|
|
.Vb 3
|
|
\& /* sign */
|
|
\& DSA_SIG *(*dsa_do_sign)(const unsigned char *dgst, int dlen,
|
|
\& DSA *dsa);
|
|
.Ve
|
|
.Vb 3
|
|
\& /* pre-compute k^-1 and r */
|
|
\& int (*dsa_sign_setup)(DSA *dsa, BN_CTX *ctx_in, BIGNUM **kinvp,
|
|
\& BIGNUM **rp);
|
|
.Ve
|
|
.Vb 3
|
|
\& /* verify */
|
|
\& int (*dsa_do_verify)(const unsigned char *dgst, int dgst_len,
|
|
\& DSA_SIG *sig, DSA *dsa);
|
|
.Ve
|
|
.Vb 5
|
|
\& /* compute rr = a1^p1 * a2^p2 mod m (May be NULL for some
|
|
\& implementations) */
|
|
\& int (*dsa_mod_exp)(DSA *dsa, BIGNUM *rr, BIGNUM *a1, BIGNUM *p1,
|
|
\& BIGNUM *a2, BIGNUM *p2, BIGNUM *m,
|
|
\& BN_CTX *ctx, BN_MONT_CTX *in_mont);
|
|
.Ve
|
|
.Vb 4
|
|
\& /* compute r = a ^ p mod m (May be NULL for some implementations) */
|
|
\& int (*bn_mod_exp)(DSA *dsa, BIGNUM *r, BIGNUM *a,
|
|
\& const BIGNUM *p, const BIGNUM *m,
|
|
\& BN_CTX *ctx, BN_MONT_CTX *m_ctx);
|
|
.Ve
|
|
.Vb 2
|
|
\& /* called at DSA_new */
|
|
\& int (*init)(DSA *DSA);
|
|
.Ve
|
|
.Vb 2
|
|
\& /* called at DSA_free */
|
|
\& int (*finish)(DSA *DSA);
|
|
.Ve
|
|
.Vb 1
|
|
\& int flags;
|
|
.Ve
|
|
.Vb 1
|
|
\& char *app_data; /* ?? */
|
|
.Ve
|
|
.Vb 1
|
|
\& } DSA_METHOD;
|
|
.Ve
|
|
.SH "RETURN VALUES"
|
|
.IX Header "RETURN VALUES"
|
|
\&\fIDSA_OpenSSL()\fR and \fIDSA_get_default_method()\fR return pointers to the respective
|
|
\&\fB\s-1DSA_METHOD\s0\fRs.
|
|
.PP
|
|
\&\fIDSA_set_default_method()\fR returns no value.
|
|
.PP
|
|
\&\fIDSA_set_method()\fR returns non-zero if the provided \fBmeth\fR was successfully set as
|
|
the method for \fBdsa\fR (including unloading the \s-1ENGINE\s0 handle if the previous
|
|
method was supplied by an \s-1ENGINE\s0).
|
|
.PP
|
|
\&\fIDSA_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-1DSA_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-1DSA\s0 functionality using an \s-1ENGINE\s0 \s-1API\s0 function,
|
|
that will override any \s-1DSA\s0 defaults set using the \s-1DSA\s0 \s-1API\s0 (ie.
|
|
\&\fIDSA_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-1DSA\s0 and other cryptographic
|
|
algorithms.
|
|
.SH "SEE ALSO"
|
|
.IX Header "SEE ALSO"
|
|
openssl_dsa(3), DSA_new(3)
|
|
.SH "HISTORY"
|
|
.IX Header "HISTORY"
|
|
\&\fIDSA_set_default_method()\fR, \fIDSA_get_default_method()\fR, \fIDSA_set_method()\fR,
|
|
\&\fIDSA_new_method()\fR and \fIDSA_OpenSSL()\fR were added in OpenSSL 0.9.4.
|
|
.PP
|
|
\&\fIDSA_set_default_openssl_method()\fR and \fIDSA_get_default_openssl_method()\fR replaced
|
|
\&\fIDSA_set_default_method()\fR and \fIDSA_get_default_method()\fR respectively, and
|
|
\&\fIDSA_set_method()\fR and \fIDSA_new_method()\fR were altered to use \fB\s-1ENGINE\s0\fRs rather than
|
|
\&\fB\s-1DSA_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-1DSA\s0 \s-1API\s0 without
|
|
requiring changing these function prototypes.
|