[thirdparty/openssl.git] / doc / crypto / RSA_set_method.pod

=pod

=head1 NAME

RSA_set_default_method, RSA_get_default_method, RSA_set_method,
RSA_get_method, RSA_PKCS1_SSLeay, RSA_PKCS1_RSAref,
RSA_null_method, RSA_flags, RSA_new_method - select RSA method

=head1 SYNOPSIS

 #include <openssl/rsa.h>

 void RSA_set_default_method(RSA_METHOD *meth);

 RSA_METHOD *RSA_get_default_method(void);

 RSA_METHOD *RSA_set_method(RSA *rsa, RSA_METHOD *meth);

 RSA_METHOD *RSA_get_method(RSA *rsa);

 RSA_METHOD *RSA_PKCS1_SSLeay(void);

 RSA_METHOD *RSA_PKCS1_RSAref(void);

 RSA_METHOD *RSA_null_method(void);

 int RSA_flags(RSA *rsa);

 RSA *RSA_new_method(RSA_METHOD *method);

=head1 DESCRIPTION

An B<RSA_METHOD> specifies the functions that OpenSSL uses for RSA
operations. By modifying the method, alternative implementations
such as hardware accelerators may be used.

Initially, the default is to use the OpenSSL internal implementation,
unless OpenSSL was configured with the C<rsaref> or C<-DRSA_NULL>
options. RSA_PKCS1_SSLeay() returns a pointer to that method.

RSA_PKCS1_RSAref() returns a pointer to a method that uses the RSAref
library. This is the default method in the C<rsaref> configuration;
the function is not available in other configurations.
RSA_null_method() returns a pointer to a method that does not support
the RSA transformation. It is the default if OpenSSL is compiled with
C<-DRSA_NULL>. These methods may be useful in the USA because of a
patent on the RSA cryptosystem.

RSA_set_default_method() makes B<meth> the default method for all B<RSA>
structures created later.

RSA_get_default_method() returns a pointer to the current default
method.

RSA_set_method() selects B<meth> for all operations using the key
B<rsa>.

RSA_get_method() returns a pointer to the method currently selected
for B<rsa>.

RSA_flags() returns the B<flags> that are set for B<rsa>'s current method.

RSA_new_method() allocates and initializes an B<RSA> structure so that
B<method> will be used for the RSA operations. If B<method> is B<NULL>,
the default method is used.

=head1 THE RSA_METHOD STRUCTURE

 typedef struct rsa_meth_st
 {
     /* name of the implementation */
	const char *name;

     /* encrypt */
	int (*rsa_pub_enc)(int flen, unsigned char *from,
          unsigned char *to, RSA *rsa, int padding);

     /* verify arbitrary data */
	int (*rsa_pub_dec)(int flen, unsigned char *from,
          unsigned char *to, RSA *rsa, int padding);

     /* sign arbitrary data */
	int (*rsa_priv_enc)(int flen, unsigned char *from,
          unsigned char *to, RSA *rsa, int padding);

     /* decrypt */
	int (*rsa_priv_dec)(int flen, unsigned char *from,
          unsigned char *to, RSA *rsa, int padding);

     /* compute r0 = r0 ^ I mod rsa->n (May be NULL for some
                                        implementations) */
	int (*rsa_mod_exp)(BIGNUM *r0, BIGNUM *I, RSA *rsa);

     /* compute r = a ^ p mod m (May be NULL for some implementations) */
	int (*bn_mod_exp)(BIGNUM *r, BIGNUM *a, const BIGNUM *p,
          const BIGNUM *m, BN_CTX *ctx, BN_MONT_CTX *m_ctx);

     /* called at RSA_new */
	int (*init)(RSA *rsa);

     /* called at RSA_free */
	int (*finish)(RSA *rsa);

     /* RSA_FLAG_EXT_PKEY        - rsa_mod_exp is called for private key
      *                            operations, even if p,q,dmp1,dmq1,iqmp
      *                            are NULL
      * RSA_FLAG_SIGN_VER        - enable rsa_sign and rsa_verify
      * RSA_METHOD_FLAG_NO_CHECK - don't check pub/private match
      */
	int flags;

	char *app_data; /* ?? */

     /* sign. For backward compatibility, this is used only
      * if (flags & RSA_FLAG_SIGN_VER)
      */
	int (*rsa_sign)(int type, unsigned char *m, unsigned int m_len,
           unsigned char *sigret, unsigned int *siglen, RSA *rsa);

     /* verify. For backward compatibility, this is used only
      * if (flags & RSA_FLAG_SIGN_VER)
      */
	int (*rsa_verify)(int type, unsigned char *m, unsigned int m_len,
           unsigned char *sigbuf, unsigned int siglen, RSA *rsa);

 } RSA_METHOD;

=head1 RETURN VALUES

RSA_PKCS1_SSLeay(), RSA_PKCS1_RSAref(), RSA_PKCS1_null_method(),
RSA_get_default_method() and RSA_get_method() return pointers to the
respective B<RSA_METHOD>s.

RSA_set_default_method() returns no value.

RSA_set_method() returns a pointer to the B<RSA_METHOD> previously
associated with B<rsa>.

RSA_new_method() returns B<NULL> and sets an error code that can be
obtained by L<ERR_get_error(3)|ERR_get_error(3)> if the allocation fails. Otherwise it
returns a pointer to the newly allocated structure.

=head1 SEE ALSO

L<rsa(3)|rsa(3)>, L<RSA_new(3)|RSA_new(3)>

=head1 HISTORY

RSA_new_method() and RSA_set_default_method() appeared in SSLeay 0.8.
RSA_get_default_method(), RSA_set_method() and RSA_get_method() as
well as the rsa_sign and rsa_verify components of RSA_METHOD were
added in OpenSSL 0.9.4.

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