looks like a cut&paste error
[openssl.git] / doc / crypto / RSA_set_method.pod
1 =pod
2
3 =head1 NAME
4
5 RSA_set_default_method, RSA_get_default_method, RSA_set_method,
6 RSA_get_method, RSA_PKCS1_SSLeay, RSA_PKCS1_RSAref,
7 RSA_null_method, RSA_flags, RSA_new_method - select RSA method
8
9 =head1 SYNOPSIS
10
11  #include <openssl/rsa.h>
12  #include <openssl/engine.h>
13
14  void RSA_set_default_openssl_method(RSA_METHOD *meth);
15
16  RSA_METHOD *RSA_get_default_openssl_method(void);
17
18  int RSA_set_method(RSA *rsa, ENGINE *engine);
19
20  RSA_METHOD *RSA_get_method(RSA *rsa);
21
22  RSA_METHOD *RSA_PKCS1_SSLeay(void);
23
24  RSA_METHOD *RSA_PKCS1_RSAref(void);
25
26  RSA_METHOD *RSA_null_method(void);
27
28  int RSA_flags(RSA *rsa);
29
30  RSA *RSA_new_method(ENGINE *engine);
31
32 =head1 DESCRIPTION
33
34 An B<RSA_METHOD> specifies the functions that OpenSSL uses for RSA
35 operations. By modifying the method, alternative implementations
36 such as hardware accelerators may be used.
37
38 Initially, the default is to use the OpenSSL internal implementation,
39 unless OpenSSL was configured with the C<rsaref> or C<-DRSA_NULL>
40 options. RSA_PKCS1_SSLeay() returns a pointer to that method.
41
42 RSA_PKCS1_RSAref() returns a pointer to a method that uses the RSAref
43 library. This is the default method in the C<rsaref> configuration;
44 the function is not available in other configurations.
45 RSA_null_method() returns a pointer to a method that does not support
46 the RSA transformation. It is the default if OpenSSL is compiled with
47 C<-DRSA_NULL>. These methods may be useful in the USA because of a
48 patent on the RSA cryptosystem.
49
50 RSA_set_default_openssl_method() makes B<meth> the default method for all B<RSA>
51 structures created later. B<NB:> This is true only whilst the default engine
52 for RSA operations remains as "openssl". ENGINEs provide an
53 encapsulation for implementations of one or more algorithms at a time, and all
54 the RSA functions mentioned here operate within the scope of the default
55 "openssl" engine.
56
57 RSA_get_default_openssl_method() returns a pointer to the current default
58 method for the "openssl" engine.
59
60 RSA_set_method() selects B<engine> for all operations using the key
61 B<rsa>.
62
63 RSA_get_method() returns a pointer to the RSA_METHOD from the currently
64 selected ENGINE for B<rsa>.
65
66 RSA_flags() returns the B<flags> that are set for B<rsa>'s current method.
67
68 RSA_new_method() allocates and initializes an RSA structure so that
69 B<engine> will be used for the RSA operations. If B<engine> is NULL,
70 the default engine for RSA operations is used.
71
72 =head1 THE RSA_METHOD STRUCTURE
73
74  typedef struct rsa_meth_st
75  {
76      /* name of the implementation */
77         const char *name;
78
79      /* encrypt */
80         int (*rsa_pub_enc)(int flen, unsigned char *from,
81           unsigned char *to, RSA *rsa, int padding);
82
83      /* verify arbitrary data */
84         int (*rsa_pub_dec)(int flen, unsigned char *from,
85           unsigned char *to, RSA *rsa, int padding);
86
87      /* sign arbitrary data */
88         int (*rsa_priv_enc)(int flen, unsigned char *from,
89           unsigned char *to, RSA *rsa, int padding);
90
91      /* decrypt */
92         int (*rsa_priv_dec)(int flen, unsigned char *from,
93           unsigned char *to, RSA *rsa, int padding);
94
95      /* compute r0 = r0 ^ I mod rsa->n (May be NULL for some
96                                         implementations) */
97         int (*rsa_mod_exp)(BIGNUM *r0, BIGNUM *I, RSA *rsa);
98
99      /* compute r = a ^ p mod m (May be NULL for some implementations) */
100         int (*bn_mod_exp)(BIGNUM *r, BIGNUM *a, const BIGNUM *p,
101           const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx);
102
103      /* called at RSA_new */
104         int (*init)(RSA *rsa);
105
106      /* called at RSA_free */
107         int (*finish)(RSA *rsa);
108
109      /* RSA_FLAG_EXT_PKEY        - rsa_mod_exp is called for private key
110       *                            operations, even if p,q,dmp1,dmq1,iqmp
111       *                            are NULL
112       * RSA_FLAG_SIGN_VER        - enable rsa_sign and rsa_verify
113       * RSA_METHOD_FLAG_NO_CHECK - don't check pub/private match
114       */
115         int flags;
116
117         char *app_data; /* ?? */
118
119      /* sign. For backward compatibility, this is used only
120       * if (flags & RSA_FLAG_SIGN_VER)
121       */
122         int (*rsa_sign)(int type, unsigned char *m, unsigned int m_len,
123            unsigned char *sigret, unsigned int *siglen, RSA *rsa);
124
125      /* verify. For backward compatibility, this is used only
126       * if (flags & RSA_FLAG_SIGN_VER)
127       */
128         int (*rsa_verify)(int type, unsigned char *m, unsigned int m_len,
129            unsigned char *sigbuf, unsigned int siglen, RSA *rsa);
130
131  } RSA_METHOD;
132
133 =head1 RETURN VALUES
134
135 RSA_PKCS1_SSLeay(), RSA_PKCS1_RSAref(), RSA_PKCS1_null_method(),
136 RSA_get_default_openssl_method() and RSA_get_method() return pointers to
137 the respective RSA_METHODs.
138
139 RSA_set_default_openssl_method() returns no value.
140
141 RSA_set_method() selects B<engine> as the engine that will be responsible for
142 all operations using the structure B<rsa>. If this function completes successfully,
143 then the B<rsa> structure will have its own functional reference of B<engine>, so
144 the caller should remember to free their own reference to B<engine> when they are
145 finished with it. NB: An ENGINE's RSA_METHOD can be retrieved (or set) by
146 ENGINE_get_RSA() or ENGINE_set_RSA().
147
148 RSA_new_method() returns NULL and sets an error code that can be
149 obtained by L<ERR_get_error(3)|ERR_get_error(3)> if the allocation fails. Otherwise
150 it returns a pointer to the newly allocated structure.
151
152 =head1 SEE ALSO
153
154 L<rsa(3)|rsa(3)>, L<RSA_new(3)|RSA_new(3)>
155
156 =head1 HISTORY
157
158 RSA_new_method() and RSA_set_default_method() appeared in SSLeay 0.8.
159 RSA_get_default_method(), RSA_set_method() and RSA_get_method() as
160 well as the rsa_sign and rsa_verify components of RSA_METHOD were
161 added in OpenSSL 0.9.4.
162
163 RSA_set_default_openssl_method() and RSA_get_default_openssl_method()
164 replaced RSA_set_default_method() and RSA_get_default_method() respectively,
165 and RSA_set_method() and RSA_new_method() were altered to use B<ENGINE>s
166 rather than B<RSA_METHOD>s during development of OpenSSL 0.9.6.
167
168 =cut