]>
Commit | Line | Data |
---|---|---|
38e33cef UM |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5bf73873 | 5 | DSA_set_default_method, DSA_get_default_method, |
5270e702 | 6 | DSA_set_method, DSA_new_method, DSA_OpenSSL - select DSA method |
38e33cef UM |
7 | |
8 | =head1 SYNOPSIS | |
9 | ||
4c0aee5a | 10 | #include <openssl/dsa.h> |
6aba658c | 11 | #include <openssl/engine.h> |
38e33cef | 12 | |
5bf73873 | 13 | void DSA_set_default_method(const DSA_METHOD *meth); |
38e33cef | 14 | |
5bf73873 | 15 | const DSA_METHOD *DSA_get_default_method(void); |
38e33cef | 16 | |
5bf73873 | 17 | int DSA_set_method(DSA *dsa, const DSA_METHOD *meth); |
38e33cef | 18 | |
6aba658c | 19 | DSA *DSA_new_method(ENGINE *engine); |
38e33cef UM |
20 | |
21 | DSA_METHOD *DSA_OpenSSL(void); | |
22 | ||
23 | =head1 DESCRIPTION | |
24 | ||
25 | A B<DSA_METHOD> specifies the functions that OpenSSL uses for DSA | |
26 | operations. By modifying the method, alternative implementations | |
5bf73873 GT |
27 | such as hardware accelerators may be used. IMPORTANT: See the NOTES section for |
28 | important information about how these DSA API functions are affected by the use | |
29 | of B<ENGINE> API calls. | |
30 | ||
31 | Initially, the default DSA_METHOD is the OpenSSL internal implementation, | |
32 | as returned by DSA_OpenSSL(). | |
33 | ||
34 | DSA_set_default_method() makes B<meth> the default method for all DSA | |
35 | structures created later. B<NB>: This is true only whilst no ENGINE has | |
36 | been set as a default for DSA, so this function is no longer recommended. | |
37 | ||
38 | DSA_get_default_method() returns a pointer to the current default | |
b6a338cb | 39 | DSA_METHOD. However, the meaningfulness of this result is dependent on |
5bf73873 GT |
40 | whether the ENGINE API is being used, so this function is no longer |
41 | recommended. | |
42 | ||
43 | DSA_set_method() selects B<meth> to perform all operations using the key | |
44 | B<rsa>. This will replace the DSA_METHOD used by the DSA key and if the | |
45 | previous method was supplied by an ENGINE, the handle to that ENGINE will | |
46 | be released during the change. It is possible to have DSA keys that only | |
47 | work with certain DSA_METHOD implementations (eg. from an ENGINE module | |
48 | that supports embedded hardware-protected keys), and in such cases | |
49 | attempting to change the DSA_METHOD for the key can have unexpected | |
50 | results. | |
51 | ||
52 | DSA_new_method() allocates and initializes a DSA structure so that B<engine> | |
53 | will be used for the DSA operations. If B<engine> is NULL, the default engine | |
54 | for DSA operations is used, and if no default ENGINE is set, the DSA_METHOD | |
55 | controlled by DSA_set_default_method() is used. | |
38e33cef UM |
56 | |
57 | =head1 THE DSA_METHOD STRUCTURE | |
58 | ||
59 | struct | |
60 | { | |
61 | /* name of the implementation */ | |
74235cc9 | 62 | const char *name; |
38e33cef UM |
63 | |
64 | /* sign */ | |
65 | DSA_SIG *(*dsa_do_sign)(const unsigned char *dgst, int dlen, | |
66 | DSA *dsa); | |
67 | ||
68 | /* pre-compute k^-1 and r */ | |
69 | int (*dsa_sign_setup)(DSA *dsa, BN_CTX *ctx_in, BIGNUM **kinvp, | |
70 | BIGNUM **rp); | |
71 | ||
72 | /* verify */ | |
73 | int (*dsa_do_verify)(const unsigned char *dgst, int dgst_len, | |
74 | DSA_SIG *sig, DSA *dsa); | |
75 | ||
e4947bfe UM |
76 | /* compute rr = a1^p1 * a2^p2 mod m (May be NULL for some |
77 | implementations) */ | |
38e33cef UM |
78 | int (*dsa_mod_exp)(DSA *dsa, BIGNUM *rr, BIGNUM *a1, BIGNUM *p1, |
79 | BIGNUM *a2, BIGNUM *p2, BIGNUM *m, | |
80 | BN_CTX *ctx, BN_MONT_CTX *in_mont); | |
81 | ||
e4947bfe | 82 | /* compute r = a ^ p mod m (May be NULL for some implementations) */ |
74235cc9 UM |
83 | int (*bn_mod_exp)(DSA *dsa, BIGNUM *r, BIGNUM *a, |
84 | const BIGNUM *p, const BIGNUM *m, | |
85 | BN_CTX *ctx, BN_MONT_CTX *m_ctx); | |
38e33cef UM |
86 | |
87 | /* called at DSA_new */ | |
88 | int (*init)(DSA *DSA); | |
89 | ||
90 | /* called at DSA_free */ | |
91 | int (*finish)(DSA *DSA); | |
92 | ||
93 | int flags; | |
94 | ||
95 | char *app_data; /* ?? */ | |
96 | ||
97 | } DSA_METHOD; | |
98 | ||
99 | =head1 RETURN VALUES | |
100 | ||
5bf73873 GT |
101 | DSA_OpenSSL() and DSA_get_default_method() return pointers to the respective |
102 | B<DSA_METHOD>s. | |
38e33cef | 103 | |
5bf73873 | 104 | DSA_set_default_method() returns no value. |
38e33cef | 105 | |
5bf73873 GT |
106 | DSA_set_method() returns non-zero if the provided B<meth> was successfully set as |
107 | the method for B<dsa> (including unloading the ENGINE handle if the previous | |
108 | method was supplied by an ENGINE). | |
38e33cef | 109 | |
5270e702 | 110 | DSA_new_method() returns NULL and sets an error code that can be |
9b86974e | 111 | obtained by L<ERR_get_error(3)> if the allocation |
5270e702 | 112 | fails. Otherwise it returns a pointer to the newly allocated structure. |
38e33cef | 113 | |
5bf73873 GT |
114 | =head1 NOTES |
115 | ||
116 | As of version 0.9.7, DSA_METHOD implementations are grouped together with other | |
117 | algorithmic APIs (eg. RSA_METHOD, EVP_CIPHER, etc) in B<ENGINE> modules. If a | |
118 | default ENGINE is specified for DSA functionality using an ENGINE API function, | |
119 | that will override any DSA defaults set using the DSA API (ie. | |
120 | DSA_set_default_method()). For this reason, the ENGINE API is the recommended way | |
121 | to control default implementations for use in DSA and other cryptographic | |
122 | algorithms. | |
123 | ||
38e33cef UM |
124 | =head1 SEE ALSO |
125 | ||
9b86974e | 126 | L<dsa(3)>, L<DSA_new(3)> |
38e33cef UM |
127 | |
128 | =head1 HISTORY | |
129 | ||
130 | DSA_set_default_method(), DSA_get_default_method(), DSA_set_method(), | |
131 | DSA_new_method() and DSA_OpenSSL() were added in OpenSSL 0.9.4. | |
132 | ||
5bf73873 GT |
133 | DSA_set_default_openssl_method() and DSA_get_default_openssl_method() replaced |
134 | DSA_set_default_method() and DSA_get_default_method() respectively, and | |
135 | DSA_set_method() and DSA_new_method() were altered to use B<ENGINE>s rather than | |
136 | B<DSA_METHOD>s during development of the engine version of OpenSSL 0.9.6. For | |
137 | 0.9.7, the handling of defaults in the ENGINE API was restructured so that this | |
138 | change was reversed, and behaviour of the other functions resembled more closely | |
139 | the previous behaviour. The behaviour of defaults in the ENGINE API now | |
140 | transparently overrides the behaviour of defaults in the DSA API without | |
141 | requiring changing these function prototypes. | |
5270e702 | 142 | |
38e33cef | 143 | =cut |